@dynamic-labs-wallet/node 0.0.354 → 1.0.0-beta

package/index.cjs

@@ -8,7 +8,7 @@ var logger = require('@dynamic-labs/logger');
 var forwardMpcClient = require('@dynamic-labs-wallet/forward-mpc-client');
 var uuid = require('uuid');
 var crypto = require('crypto');
-require('node:crypto');
+var crypto$1 = require('node:crypto');
 
 // Removed duplicate exports - these are already exported from #internal/core
 const getMPCSignatureScheme = ({ signingAlgorithm, baseRelayUrl = core$1.MPC_RELAY_PROD_API_URL })=>{
@@ -317,6 +317,33 @@ class DynamicWalletClient {
             throw new Error('Client must be authenticated before making API calls. Call authenticateApiToken first.');
         }
     }
+    /**
+   * Guards against silent operate-on-different-wallet bugs when callers pass
+   * both `accountAddress` and `walletMetadata`. Throws when either is missing
+   * or when they disagree.
+   *
+   * Comparison is case-insensitive only for EVM (where checksum casing is
+   * decoration over an underlying hex address). SVM (base58), BTC base58,
+   * and TON (base64url) are case-sensitive — two addresses that differ only
+   * in case are different addresses.
+   */ assertAddressMatchesMetadata(accountAddress, walletMetadata) {
+        var _walletMetadata_chainName;
+        if (!accountAddress) {
+            throw new Error('accountAddress is required and must not be empty.');
+        }
+        if (!walletMetadata.accountAddress) {
+            throw new Error('walletMetadata.accountAddress is required and must not be empty.');
+        }
+        // chainName comparison is case-insensitive — chain clients set the
+        // canonical uppercase form, but server-fetched walletMetadata could
+        // theoretically arrive with a different case.
+        const isEvm = ((_walletMetadata_chainName = walletMetadata.chainName) == null ? void 0 : _walletMetadata_chainName.toUpperCase()) === 'EVM';
+        const left = isEvm ? accountAddress.toLowerCase() : accountAddress;
+        const right = isEvm ? walletMetadata.accountAddress.toLowerCase() : walletMetadata.accountAddress;
+        if (left !== right) {
+            throw new Error('accountAddress mismatch: parameter does not match walletMetadata.accountAddress. ' + 'Pass them consistently — preferably read from walletMetadata.accountAddress.');
+        }
+    }
     async authenticateApiToken(authToken) {
         const tmpClient = new core$1.DynamicApiClient({
             environmentId: this.environmentId,
@@ -338,6 +365,57 @@ class DynamicWalletClient {
         });
         this.isApiClientAuthenticated = true;
     }
+    /**
+   * Fetches non-sensitive wallet identity (walletId, accountAddress, chainName,
+   * derivationPath, thresholdSignatureScheme) from the Dynamic API by
+   * `accountAddress`. SDK-scoped — works with the customer auth token from
+   * `authenticateApiToken`.
+   *
+   * **What this returns and what it does NOT return:**
+   * - Returns: wallet identity fields above.
+   * - Does NOT return: `externalServerKeySharesBackupInfo` (the per-share
+   *   pointer metadata that drives recovery), `addressType`, or any
+   *   encrypted material. The byAddress endpoint is intentionally a slim
+   *   identity lookup; pointer metadata and addressType only come from the
+   *   `createWalletAccount` / `importPrivateKey` return values.
+   *
+   * **Customer responsibility:**
+   * Persist the FULL `walletMetadata` returned by `createWalletAccount` /
+   * `importPrivateKey` (which includes `externalServerKeySharesBackupInfo` and
+   * `addressType`). `fetchWalletMetadata` recovers identity only — it cannot
+   * substitute for a properly-cached `walletMetadata` after a Redis wipe if
+   * the operation needs `backupInfo` (sign with auto-recovery, password
+   * checks, refresh, etc.).
+   *
+   * Does not cache, does not mutate SDK state.
+   */ async fetchWalletMetadata(accountAddress) {
+        this.ensureApiClientAuthenticated();
+        const { wallet } = await this.apiClient.getWaasWalletByAddress({
+            walletAddress: accountAddress
+        });
+        return {
+            walletId: wallet.walletId,
+            accountAddress: wallet.accountAddress,
+            chainName: wallet.chainName,
+            thresholdSignatureScheme: wallet.thresholdSignatureScheme,
+            derivationPath: wallet.derivationPath
+        };
+    }
+    /**
+   * Returns the cached `externalServerKeySharesBackupInfo` from
+   * `walletMetadata`. The Dynamic API does not currently expose a SDK-scoped
+   * endpoint that returns the keyShare pointer metadata by address (only the
+   * unbounded `getUser` does, which we avoid for server wallets). So the
+   * customer must persist the full `walletMetadata` (with backupInfo)
+   * returned by `createWalletAccount` / `importPrivateKey` and pass it back
+   * in on subsequent calls. Throws loudly when missing — never silently
+   * synthesizes empty state.
+   */ async resolveBackupInfo(walletMetadata) {
+        if (!walletMetadata.externalServerKeySharesBackupInfo) {
+            throw new Error('walletMetadata.externalServerKeySharesBackupInfo is required. ' + 'Persist the full walletMetadata returned by createWalletAccount/importPrivateKey ' + '(including externalServerKeySharesBackupInfo) and pass it back in on subsequent calls.');
+        }
+        return walletMetadata.externalServerKeySharesBackupInfo;
+    }
     async dynamicServerInitializeKeyGen({ chainName, externalServerKeygenIds, thresholdSignatureScheme, dynamicRequestId, skipLock, bitcoinConfig, onError, onCeremonyComplete }) {
         this.ensureApiClientAuthenticated();
         try {
@@ -514,7 +592,16 @@ class DynamicWalletClient {
             throw new Error('Error deriving public key in externalServerKeyGen');
         }
     }
-    async keyGen({ chainName, thresholdSignatureScheme, skipLock, bitcoinConfig, onError, onCeremonyComplete }) {
+    validatePasswordForBackup({ password, backUpToDynamic }) {
+        if (backUpToDynamic && (!password || password === this.environmentId)) {
+            throw new Error('A password is required when backing up to Dynamic. ' + 'You can use the same password for all wallets or a unique password per wallet.');
+        }
+    }
+    async keyGen({ chainName, thresholdSignatureScheme, skipLock, bitcoinConfig, password, backUpToDynamic, onError, onCeremonyComplete }) {
+        this.validatePasswordForBackup({
+            password,
+            backUpToDynamic
+        });
         const dynamicRequestId = uuid.v4();
         try {
             const externalServerInitKeygenResults = await this.externalServerInitializeKeyGen({
@@ -549,7 +636,11 @@ class DynamicWalletClient {
             throw new Error('Error creating wallet account in keyGen');
         }
     }
-    async importRawPrivateKey({ chainName, privateKey, thresholdSignatureScheme, bitcoinConfig, onError, onCeremonyComplete }) {
+    async importRawPrivateKey({ chainName, privateKey, thresholdSignatureScheme, bitcoinConfig, password, backUpToDynamic, onError, onCeremonyComplete }) {
+        this.validatePasswordForBackup({
+            password,
+            backUpToDynamic
+        });
         this.ensureApiClientAuthenticated();
         const dynamicRequestId = uuid.v4();
         const mpcSigner = getMPCSigner({
@@ -649,9 +740,13 @@ class DynamicWalletClient {
             this.logger.debug('Signing message with MPC Socket Client');
             const environment = core$1.getEnvironmentFromUrl(this.baseApiUrl);
             const defaultRelayUrl = core$1.MPC_RELAY_URL_MAP[environment];
+            // Ed25519 chains (SVM, TON) must send the formatted (hex) message — the
+            // forward-MPC server decodes it as hex before signing. Raw plaintext for
+            // odd-length messages produces "hex string expected, got unpadded hex of length N".
+            const isEd25519Chain = chainName === 'SVM' || chainName === 'TON';
             const { signature: signatureBytes } = await this.apiClient.forwardMPCClient.signMessage({
                 keyshare: keyShare,
-                message: chainName === 'SVM' ? formattedMessage : messageForForwardMPC,
+                message: isEd25519Chain ? formattedMessage : messageForForwardMPC,
                 relayDomain: this.baseMPCRelayApiUrl || defaultRelayUrl,
                 signingAlgo: chainName === 'EVM' ? 'ECDSA' : 'ED25519',
                 hashAlgo: chainName === 'EVM' && !isFormatted ? 'keccak256' : undefined,
@@ -719,48 +814,59 @@ class DynamicWalletClient {
             return undefined;
         }
     }
-    async sign({ accountAddress, externalServerKeyShares, message, chainName, password = undefined, isFormatted = false, context, onError, bitcoinConfig }) {
+    async sign({ accountAddress, externalServerKeyShares, message, chainName, password = undefined, isFormatted = false, context, onError, bitcoinConfig, walletMetadata, walletOperation = core$1.WalletOperation.SIGN_MESSAGE, passwordPreVerified = false }) {
         try {
-            await this.verifyPassword({
-                accountAddress,
-                password
-            });
-            const wallet = await this.getWallet({
+            this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+            const backupInfo = walletMetadata.externalServerKeySharesBackupInfo;
+            // Recover internally if no shares supplied — decryption with `password`
+            // implicitly validates it, so we won't re-run verifyPassword below.
+            const resolvedShares = externalServerKeyShares && externalServerKeyShares.length > 0 ? externalServerKeyShares : await this.resolveKeyShares({
                 accountAddress,
-                walletOperation: core$1.WalletOperation.SIGN_MESSAGE,
-                password
+                password,
+                walletOperation,
+                externalServerKeyShares,
+                errorMessage: 'External server key shares are required to sign a message',
+                walletMetadata,
+                backupInfo
             });
-            externalServerKeyShares = externalServerKeyShares != null ? externalServerKeyShares : wallet.externalServerKeyShares;
-            if (!externalServerKeyShares) {
-                var _wallet_externalServerKeySharesBackupInfo;
-                const hasExternalKeyShareId = Object.values(((_wallet_externalServerKeySharesBackupInfo = wallet.externalServerKeySharesBackupInfo) == null ? void 0 : _wallet_externalServerKeySharesBackupInfo.backups) || {}).some((locations)=>locations.some((loc)=>loc.location === core$1.BackupLocation.EXTERNAL));
-                const errorMessage = 'External server key shares are required to sign a message';
-                if (hasExternalKeyShareId) {
-                    this.logger.error(errorMessage);
-                } else {
-                    this.logger.warn(errorMessage);
+            const sharesProvided = resolvedShares === externalServerKeyShares;
+            // verifyPassword only when shares came from the caller (no implicit
+            // validation). BTC sets `passwordPreVerified` when it pre-resolved.
+            // Refuse to silently sign without verifying — missing backupInfo on
+            // this branch (e.g. caller built walletMetadata via fetchWalletMetadata
+            // identity-only path) would otherwise let any password through.
+            if (sharesProvided && !passwordPreVerified) {
+                if (!backupInfo) {
+                    throw new Error('walletMetadata.externalServerKeySharesBackupInfo is required to verify the password ' + 'when signing with caller-supplied externalServerKeyShares. Persist the full walletMetadata ' + 'returned by createWalletAccount/importPrivateKey and pass it back in. ' + 'fetchWalletMetadata returns identity-only metadata and cannot be used on this path.');
                 }
-                throw new Error(errorMessage);
+                await this.verifyPassword({
+                    accountAddress,
+                    password,
+                    walletMetadata,
+                    backupInfo
+                });
             }
+            const walletId = walletMetadata.walletId;
+            const derivationPathStr = walletMetadata.derivationPath;
             // Perform the dynamic server sign
             const data = await this.dynamicServerSign({
-                walletId: wallet.walletId,
+                walletId,
                 message,
                 isFormatted,
                 context,
                 bitcoinConfig,
                 onError
             });
-            const derivationPath = wallet.derivationPath && wallet.derivationPath != '' ? new Uint32Array(Object.values(JSON.parse(wallet.derivationPath))) : undefined;
+            const derivationPath = derivationPathStr && derivationPathStr != '' ? new Uint32Array(Object.values(JSON.parse(derivationPathStr))) : undefined;
             // Try forward MPC first if enabled, with fallback to relay-based signing on attestation failure
             const forwardMpcSignature = await this.trySignViaForwardMpc({
                 chainName,
                 message,
                 roomId: data.roomId,
-                keyShare: externalServerKeyShares[0],
+                keyShare: resolvedShares[0],
                 derivationPath,
                 isFormatted,
-                walletId: wallet.walletId,
+                walletId,
                 dynamicRequestId: data.dynamicRequestId
             });
             if (forwardMpcSignature !== undefined) {
@@ -771,7 +877,7 @@ class DynamicWalletClient {
                 chainName,
                 message,
                 roomId: data.roomId,
-                keyShare: externalServerKeyShares[0],
+                keyShare: resolvedShares[0],
                 derivationPath,
                 isFormatted,
                 bitcoinConfig
@@ -783,41 +889,47 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async refreshWalletAccountShares({ accountAddress, chainName, password = undefined, externalServerKeyShares, backUpToClientShareService = false }) {
+    async refreshWalletAccountShares({ accountAddress, chainName, password = undefined, externalServerKeyShares, backUpToDynamic = false, walletMetadata }) {
+        this.validatePasswordForBackup({
+            password,
+            backUpToDynamic
+        });
         this.ensureApiClientAuthenticated();
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const backupInfo = await this.resolveBackupInfo(walletMetadata);
         await this.verifyPassword({
             accountAddress,
-            password
-        });
-        const wallet = await this.getWallet({
-            accountAddress,
-            walletOperation: core$1.WalletOperation.REFRESH,
-            password
+            password,
+            walletMetadata,
+            backupInfo
         });
+        const bitcoinConfig = chainName === 'BTC' && walletMetadata.addressType ? {
+            addressType: walletMetadata.addressType
+        } : undefined;
         const mpcSigner = getMPCSigner({
             chainName,
-            baseRelayUrl: this.baseMPCRelayApiUrl
+            baseRelayUrl: this.baseMPCRelayApiUrl,
+            bitcoinConfig
         });
-        // Create the room and refresh the shares
         const data = await this.apiClient.refreshWalletAccountShares({
-            walletId: wallet.walletId
+            walletId: walletMetadata.walletId
         });
         const roomId = data.roomId;
-        externalServerKeyShares = externalServerKeyShares != null ? externalServerKeyShares : wallet.externalServerKeyShares;
         if (!externalServerKeyShares) {
             throw new Error('External server key shares are required to refresh');
         }
         const refreshResults = await Promise.all(externalServerKeyShares.map((serverKeyShare)=>mpcSigner.refresh(roomId, serverKeyShare)));
-        this.walletMap[accountAddress] = _extends({}, this.walletMap[accountAddress], {
-            externalServerKeyShares: refreshResults,
-            externalServerKeySharesBackupInfo: getExternalServerKeyShareBackupInfo()
-        });
-        await this.storeEncryptedBackupByWallet({
+        const { backupInfo: updatedBackupInfo } = await this.storeEncryptedBackupByWallet({
             accountAddress,
             password: password != null ? password : this.environmentId,
-            backUpToClientShareService
+            backUpToDynamic,
+            externalServerKeyShares: refreshResults,
+            walletMetadata
         });
-        return refreshResults;
+        return {
+            externalServerKeyShares: refreshResults,
+            backupInfo: updatedBackupInfo
+        };
     }
     async getExportId({ chainName, serverKeyShare, bitcoinConfig }) {
         const mpcSigner = getMPCSigner({
@@ -875,31 +987,29 @@ class DynamicWalletClient {
             existingExternalServerKeyShares
         };
     }
-    async reshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, externalServerKeyShares, backUpToClientShareService = false }) {
+    async reshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, externalServerKeyShares, backUpToDynamic = false, walletMetadata }) {
+        this.validatePasswordForBackup({
+            password,
+            backUpToDynamic
+        });
         this.ensureApiClientAuthenticated();
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const backupInfo = await this.resolveBackupInfo(walletMetadata);
         await this.verifyPassword({
             accountAddress,
-            password
-        });
-        const { existingExternalServerShareCount } = core$1.getServerWalletReshareConfig({
-            oldThresholdSignatureScheme,
-            newThresholdSignatureScheme
-        });
-        const wallet = await this.getWallet({
-            accountAddress,
-            walletOperation: core$1.WalletOperation.RESHARE,
-            shareCount: existingExternalServerShareCount,
-            password
+            password,
+            walletMetadata,
+            backupInfo
         });
-        externalServerKeyShares = externalServerKeyShares != null ? externalServerKeyShares : wallet.externalServerKeyShares;
         if (!externalServerKeyShares) {
             throw new Error('External server key shares are required to reshare');
         }
         const { newExternalServerInitKeygenResults, newExternalServerKeygenIds, existingExternalServerKeygenIds, existingExternalServerKeyShares } = await this.reshareStrategy({
             chainName,
-            wallet: _extends({}, wallet, {
+            wallet: {
+                addressType: walletMetadata.addressType,
                 externalServerKeyShares
-            }),
+            },
             oldThresholdSignatureScheme,
             newThresholdSignatureScheme
         });
@@ -907,15 +1017,13 @@ class DynamicWalletClient {
             ...newExternalServerKeygenIds,
             ...existingExternalServerKeygenIds
         ];
-        // Server to create the room and complete the server reshare logics
         const data = await this.apiClient.reshare({
-            walletId: wallet.walletId,
+            walletId: walletMetadata.walletId,
             clientKeygenIds: externalServerKeygenIds,
             oldThresholdSignatureScheme,
             newThresholdSignatureScheme
         });
         const { roomId, serverKeygenIds: dynamicServerKeygenIds, newServerKeygenIds: newDynamicServerKeygenIds = [] } = data;
-        // Get the MPC config for the threshold signature scheme
         const oldMpcConfig = core$1.MPC_CONFIG[oldThresholdSignatureScheme];
         const newMpcConfig = core$1.MPC_CONFIG[newThresholdSignatureScheme];
         const allPartyKeygenIds = [
@@ -923,40 +1031,60 @@ class DynamicWalletClient {
             ...dynamicServerKeygenIds,
             ...newDynamicServerKeygenIds
         ];
+        const bitcoinConfig = chainName === 'BTC' && walletMetadata.addressType ? {
+            addressType: walletMetadata.addressType
+        } : undefined;
         const mpcSigner = getMPCSigner({
             chainName,
-            baseRelayUrl: this.baseMPCRelayApiUrl
+            baseRelayUrl: this.baseMPCRelayApiUrl,
+            bitcoinConfig
         });
         const reshareResults = await Promise.all([
             ...newExternalServerInitKeygenResults.map((keygenResult)=>mpcSigner.reshareNewParty(roomId, oldMpcConfig.threshold, newMpcConfig.threshold, keygenResult, allPartyKeygenIds)),
             ...existingExternalServerKeyShares.map((keyShare)=>mpcSigner.reshareRemainingParty(roomId, newMpcConfig.threshold, keyShare, allPartyKeygenIds))
         ]);
-        this.walletMap[accountAddress] = _extends({}, this.walletMap[accountAddress], {
-            externalServerKeyShares: reshareResults,
-            externalServerKeySharesBackupInfo: getExternalServerKeyShareBackupInfo()
-        });
-        await this.storeEncryptedBackupByWallet({
+        const { backupInfo: updatedBackupInfo } = await this.storeEncryptedBackupByWallet({
             accountAddress,
             password,
-            backUpToClientShareService
+            backUpToDynamic,
+            externalServerKeyShares: reshareResults,
+            walletMetadata
         });
-        return reshareResults;
+        return {
+            externalServerKeyShares: reshareResults,
+            backupInfo: updatedBackupInfo
+        };
     }
-    async exportKey({ accountAddress, chainName, password = undefined, externalServerKeyShares, bitcoinConfig, elevatedAccessToken }) {
+    async exportKey({ accountAddress, chainName, password = undefined, externalServerKeyShares, bitcoinConfig, elevatedAccessToken, walletMetadata }) {
         this.ensureApiClientAuthenticated();
-        await this.verifyPassword({
-            accountAddress,
-            password
-        });
-        const wallet = await this.getWallet({
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const backupInfo = walletMetadata.externalServerKeySharesBackupInfo;
+        const resolvedShares = externalServerKeyShares && externalServerKeyShares.length > 0 ? externalServerKeyShares : await this.resolveKeyShares({
             accountAddress,
             password,
-            walletOperation: core$1.WalletOperation.EXPORT_PRIVATE_KEY
+            walletOperation: core$1.WalletOperation.EXPORT_PRIVATE_KEY,
+            externalServerKeyShares,
+            errorMessage: 'External server key shares are required to export a private key',
+            walletMetadata,
+            backupInfo
         });
-        externalServerKeyShares = externalServerKeyShares != null ? externalServerKeyShares : wallet.externalServerKeyShares;
-        if (!externalServerKeyShares) {
-            throw new Error('External server key shares are required to export a private key');
+        const sharesProvided = resolvedShares === externalServerKeyShares;
+        // Refuse to export without verifying — exportKey returns the raw private
+        // key, so a missing backupInfo on the caller-supplied branch would let
+        // any password through. See sign() for the analogous guard.
+        if (sharesProvided) {
+            if (!backupInfo) {
+                throw new Error('walletMetadata.externalServerKeySharesBackupInfo is required to verify the password ' + 'when exporting with caller-supplied externalServerKeyShares. Persist the full walletMetadata ' + 'returned by createWalletAccount/importPrivateKey and pass it back in. ' + 'fetchWalletMetadata returns identity-only metadata and cannot be used on this path.');
+            }
+            await this.verifyPassword({
+                accountAddress,
+                password,
+                walletMetadata,
+                backupInfo
+            });
         }
+        const walletId = walletMetadata.walletId;
+        const derivationPathStr = walletMetadata.derivationPath;
         const mpcSigner = getMPCSigner({
             chainName,
             baseRelayUrl: this.baseMPCRelayApiUrl,
@@ -964,20 +1092,20 @@ class DynamicWalletClient {
         });
         const exportId = await this.getExportId({
             chainName,
-            serverKeyShare: externalServerKeyShares[0],
+            serverKeyShare: resolvedShares[0],
             bitcoinConfig
         });
         const data = await this.apiClient.exportKey({
-            walletId: wallet.walletId,
+            walletId,
             exportId,
             bitcoinConfig,
             elevatedAccessToken
         });
-        const keyExportRaw = await mpcSigner.exportFullPrivateKey(data.roomId, externalServerKeyShares[0], exportId);
+        const keyExportRaw = await mpcSigner.exportFullPrivateKey(data.roomId, resolvedShares[0], exportId);
         if (!keyExportRaw) {
             throw new Error('Error exporting private key');
         }
-        const derivationPath = wallet.derivationPath && wallet.derivationPath != '' ? new Uint32Array(Object.values(JSON.parse(wallet.derivationPath))) : undefined;
+        const derivationPath = derivationPathStr && derivationPathStr != '' ? new Uint32Array(Object.values(JSON.parse(derivationPathStr))) : undefined;
         let derivedPrivateKey;
         if (mpcSigner instanceof node.Ecdsa) {
             derivedPrivateKey = await mpcSigner.derivePrivateKeyFromXpriv(keyExportRaw, derivationPath);
@@ -1034,53 +1162,36 @@ class DynamicWalletClient {
         const serializedEncryptedKeyShare = Buffer.from(JSON.stringify(encryptedKeyShare)).toString('base64');
         return serializedEncryptedKeyShare;
     }
-    async ensureCeremonyCompletionBeforeBackup({ accountAddress }) {
-        let retries = 0;
-        const maxRetries = 3;
-        while((!this.walletMap[accountAddress] || !this.walletMap[accountAddress].walletId) && retries < maxRetries){
-            await new Promise((resolve)=>setTimeout(resolve, 1000)); // Wait 1 second
-            retries++;
-        }
-        if (!this.walletMap[accountAddress] || !this.walletMap[accountAddress].walletId) {
-            throw new Error('Ceremony completion timeout');
-        }
-    }
-    async storeEncryptedBackupByWallet({ accountAddress, externalServerKeyShares = undefined, password = undefined, backUpToClientShareService }) {
+    async storeEncryptedBackupByWallet({ accountAddress, externalServerKeyShares = undefined, password = undefined, backUpToDynamic, walletMetadata }) {
         this.ensureApiClientAuthenticated();
-        //add retry logic for ceremony completion to prevent race condition
-        await this.ensureCeremonyCompletionBeforeBackup({
-            accountAddress
-        });
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
         const dynamicRequestId = uuid.v4();
         try {
             const keySharesToBackup = externalServerKeyShares != null ? externalServerKeyShares : await this.getExternalServerKeyShares({
                 accountAddress,
-                password
+                password,
+                walletMetadata
             });
             if (!keySharesToBackup || keySharesToBackup.length === 0) {
-                throw new Error(`Key shares not found for accountAddress: ${accountAddress}`);
+                throw new Error('Key shares not found for the requested wallet.');
             }
             const encryptedKeyShares = await Promise.all(keySharesToBackup.map((keyShare)=>this.encryptKeyShare({
                     keyShare,
                     password
                 })));
-            if (!this.walletMap[accountAddress] || !this.walletMap[accountAddress].walletId) {
-                throw new Error(`WalletId not found for accountAddress: ${accountAddress}`);
-            }
+            const { walletId, chainName, addressType } = walletMetadata;
             const passwordEncryptedFlag = Boolean(password) && password !== this.environmentId;
-            // Derive bitcoinConfig for BTC wallets
-            const walletData = this.walletMap[accountAddress];
-            const bitcoinConfig = walletData.chainName === 'BTC' && walletData.addressType ? {
-                addressType: walletData.addressType
+            const bitcoinConfig = chainName === 'BTC' && addressType ? {
+                addressType: addressType
             } : undefined;
             // Build locations + result for all shares
             const locations = [];
             const result = [];
             // Upload first share to Dynamic if requested
-            if (backUpToClientShareService) {
+            if (backUpToDynamic) {
                 const keyShareToBackupToDynamic = keySharesToBackup[0];
                 const data = await this.apiClient.storeEncryptedBackupByWallet({
-                    walletId: this.walletMap[accountAddress].walletId,
+                    walletId,
                     encryptedKeyShares: [
                         encryptedKeyShares[0]
                     ],
@@ -1090,12 +1201,17 @@ class DynamicWalletClient {
                     dynamicRequestId
                 });
                 const keygenId = await this.getExportId({
-                    chainName: walletData.chainName,
+                    chainName,
                     serverKeyShare: keyShareToBackupToDynamic,
                     bitcoinConfig
                 });
                 locations.push({
                     location: core$1.BackupLocation.DYNAMIC,
+                    // `id` and `externalKeyShareId` are the same server-assigned identifier
+                    // for dynamic backups; populating both keeps the synthesized backupInfo
+                    // shape identical to what `getExternalServerKeyShareBackupInfo` produces
+                    // from the API response (used by fetchWalletMetadata / getWalletByAddress).
+                    id: data.keyShareIds[0],
                     externalKeyShareId: data.keyShareIds[0],
                     passwordEncrypted: passwordEncryptedFlag,
                     keygenId
@@ -1105,10 +1221,10 @@ class DynamicWalletClient {
                     backedUpToClientKeyShareService: true
                 });
             }
-            const keySharesNotToBackupToDynamic = backUpToClientShareService ? keySharesToBackup.slice(1) : keySharesToBackup;
+            const keySharesNotToBackupToDynamic = backUpToDynamic ? keySharesToBackup.slice(1) : keySharesToBackup;
             for (const keyShare of keySharesNotToBackupToDynamic){
                 const keygenId = await this.getExportId({
-                    chainName: walletData.chainName,
+                    chainName,
                     serverKeyShare: keyShare,
                     bitcoinConfig
                 });
@@ -1122,28 +1238,53 @@ class DynamicWalletClient {
                     backedUpToClientKeyShareService: false
                 });
             }
-            const backupData = await this.apiClient.markKeySharesAsBackedUp({
-                walletId: this.walletMap[accountAddress].walletId,
+            const markResponse = await this.apiClient.markKeySharesAsBackedUp({
+                walletId,
                 locations,
                 dynamicRequestId
             });
-            const updatedBackupInfo = getExternalServerKeyShareBackupInfo({
-                walletProperties: {
-                    derivationPath: this.walletMap[accountAddress].derivationPath,
-                    keyShares: backupData.locationsWithKeyShares.map((ks)=>({
-                            id: ks.id,
-                            keygenId: ks.keygenId,
-                            backupLocation: ks.location,
-                            externalKeyShareId: ks.externalKeyShareId,
-                            passwordEncrypted: passwordEncryptedFlag
-                        })),
-                    thresholdSignatureScheme: this.walletMap[accountAddress].thresholdSignatureScheme
-                }
-            });
-            this.walletMap[accountAddress] = _extends({}, this.walletMap[accountAddress], {
-                externalServerKeySharesBackupInfo: updatedBackupInfo
-            });
-            return result;
+            // Build backupInfo from the server response (`locationsWithKeyShares`) so
+            // the cached backupInfo always agrees with what the server actually
+            // stored — even if the server normalizes ids/keygenIds. The server
+            // response does not include `passwordEncrypted` per location, so merge
+            // the local `passwordEncryptedFlag` (a single boolean for this batch).
+            // The fallback to local `locations` is defensive; warn loudly when it
+            // fires so a server contract regression doesn't silently degrade.
+            if (!(markResponse == null ? void 0 : markResponse.locationsWithKeyShares)) {
+                this.logger.warn('markKeySharesAsBackedUp response missing locationsWithKeyShares; falling back to local synthesis. ' + 'This may indicate a server contract regression.');
+            }
+            var _markResponse_locationsWithKeyShares;
+            const serverLocations = (_markResponse_locationsWithKeyShares = markResponse == null ? void 0 : markResponse.locationsWithKeyShares) != null ? _markResponse_locationsWithKeyShares : locations;
+            const backupInfo = {
+                backups: serverLocations.reduce((acc, loc)=>{
+                    // Defensive: if the server returns an unrecognized location enum
+                    // (e.g. a future BackupLocation we don't know yet), initialize
+                    // the bucket rather than throwing on `acc[unknown].push(...)`.
+                    if (!acc[loc.location]) {
+                        acc[loc.location] = [];
+                    }
+                    acc[loc.location].push({
+                        location: loc.location,
+                        id: loc.id,
+                        keygenId: loc.keygenId,
+                        externalKeyShareId: loc.externalKeyShareId,
+                        passwordEncrypted: passwordEncryptedFlag
+                    });
+                    return acc;
+                }, {
+                    [core$1.BackupLocation.DYNAMIC]: [],
+                    [core$1.BackupLocation.GOOGLE_DRIVE]: [],
+                    [core$1.BackupLocation.ICLOUD]: [],
+                    [core$1.BackupLocation.USER]: [],
+                    [core$1.BackupLocation.EXTERNAL]: [],
+                    [core$1.BackupLocation.DELEGATED]: []
+                }),
+                passwordEncrypted: passwordEncryptedFlag
+            };
+            return {
+                keySharesWithBackupStatus: result,
+                backupInfo
+            };
         } catch (error) {
             this.logger.error('Error in storeEncryptedBackupByWallet:', {
                 accountAddress,
@@ -1153,12 +1294,13 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async storeEncryptedBackupByWalletWithRetry({ accountAddress, externalServerKeyShares, password, backUpToClientShareService }) {
+    async storeEncryptedBackupByWalletWithRetry({ accountAddress, externalServerKeyShares, password, backUpToDynamic, walletMetadata }) {
         return retryPromise(()=>this.storeEncryptedBackupByWallet({
                 accountAddress,
                 externalServerKeyShares,
                 password,
-                backUpToClientShareService
+                backUpToDynamic,
+                walletMetadata
             }), {
             operationName: 'store encrypted backup',
             logContext: {
@@ -1166,15 +1308,12 @@ class DynamicWalletClient {
             }
         });
     }
-    async getExternalServerKeyShares({ accountAddress, password }) {
-        var _wallet_externalServerKeySharesBackupInfo_backups, _wallet_externalServerKeySharesBackupInfo;
-        const wallet = await this.getWallet({
-            accountAddress,
-            password,
-            walletOperation: core$1.WalletOperation.REACH_THRESHOLD
-        });
+    async getExternalServerKeyShares({ accountAddress, password, walletMetadata, backupInfo }) {
+        var _resolvedBackupInfo_backups;
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const resolvedBackupInfo = backupInfo != null ? backupInfo : await this.resolveBackupInfo(walletMetadata);
         // Check if the wallet has a dynamic backup and derive password encryption status from the first dynamic share
-        const dynamicBackups = (wallet == null ? void 0 : (_wallet_externalServerKeySharesBackupInfo = wallet.externalServerKeySharesBackupInfo) == null ? void 0 : (_wallet_externalServerKeySharesBackupInfo_backups = _wallet_externalServerKeySharesBackupInfo.backups) == null ? void 0 : _wallet_externalServerKeySharesBackupInfo_backups.dynamic) || [];
+        const dynamicBackups = (resolvedBackupInfo == null ? void 0 : (_resolvedBackupInfo_backups = resolvedBackupInfo.backups) == null ? void 0 : _resolvedBackupInfo_backups.dynamic) || [];
         const passwordEncrypted = dynamicBackups.length > 0 ? Boolean(dynamicBackups[0].passwordEncrypted) : false;
         if (passwordEncrypted && !password) {
             throw new Error('Password is required for decryption but not provided. This backup was encrypted with a password.');
@@ -1183,21 +1322,36 @@ class DynamicWalletClient {
         const recoveredShares = await this.recoverEncryptedBackupByWallet({
             accountAddress,
             password,
-            walletOperation: core$1.WalletOperation.REACH_THRESHOLD
+            walletOperation: core$1.WalletOperation.REACH_THRESHOLD,
+            walletMetadata,
+            backupInfo: resolvedBackupInfo
         });
         return recoveredShares;
     }
-    async updatePassword({ accountAddress, existingPassword, newPassword, backUpToClientShareService }) {
-        await this.getWallet({
+    async updatePassword({ accountAddress, existingPassword, newPassword, backUpToDynamic, externalServerKeyShares, walletMetadata }) {
+        this.validatePasswordForBackup({
+            password: newPassword,
+            backUpToDynamic
+        });
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const sharesToBackup = await this.resolveKeyShares({
             accountAddress,
             password: existingPassword,
-            walletOperation: core$1.WalletOperation.REACH_ALL_PARTIES
+            walletOperation: core$1.WalletOperation.REACH_ALL_PARTIES,
+            externalServerKeyShares,
+            errorMessage: 'External server key shares are required to update password',
+            walletMetadata
         });
-        await this.storeEncryptedBackupByWallet({
+        const { backupInfo } = await this.storeEncryptedBackupByWallet({
             accountAddress,
             password: newPassword,
-            backUpToClientShareService
+            backUpToDynamic,
+            externalServerKeyShares: sharesToBackup,
+            walletMetadata
         });
+        return {
+            backupInfo
+        };
     }
     async decryptKeyShare({ keyShare, password }) {
         const decodedKeyShare = JSON.parse(Buffer.from(keyShare, 'base64').toString());
@@ -1242,49 +1396,45 @@ class DynamicWalletClient {
         };
     }
     /**
-   * Attempts to recover key shares from backup if they are not provided.
-   * The recovered shares will be stored in the wallet map for use in signing operations.
-   * @param accountAddress - The account address to recover shares for
+   * Resolves and returns key shares for wallet operations.
+   * Checks in order: provided shares, then attempts recovery from backup.
+   * @param accountAddress - The account address to get shares for
    * @param password - The password to decrypt the shares
    * @param walletOperation - The wallet operation being performed
    * @param externalServerKeyShares - The provided key shares (if any)
-   * @param errorMessage - The error message to throw if recovery fails
-   * @throws Error if recovery is needed but fails
-   */ async ensureKeySharesRecovered({ accountAddress, password, walletOperation, externalServerKeyShares, errorMessage }) {
-        if (!externalServerKeyShares || externalServerKeyShares.length === 0) {
-            // attempt to recover dynamic keyshares if no key shares are provided
-            // the shares will be used for signing in the node SDK if successful
-            const recoveredShares = await this.recoverEncryptedBackupByWallet({
-                accountAddress,
-                password,
-                walletOperation,
-                storeRecoveredShares: true
-            });
-            // If recovery returned empty and no shares were provided, throw error
-            if (!recoveredShares || recoveredShares.length === 0) {
-                throw new Error(errorMessage);
-            }
+   * @param errorMessage - The error message to throw if no shares are found
+   * @param walletMetadata - Required wallet metadata identifying the target wallet
+   * @returns The resolved key shares
+   * @throws Error if no shares are found and recovery fails
+   */ async resolveKeyShares({ accountAddress, password, walletOperation, externalServerKeyShares, errorMessage, walletMetadata, backupInfo }) {
+        if (externalServerKeyShares == null ? void 0 : externalServerKeyShares.length) {
+            return externalServerKeyShares;
+        }
+        const recoveredShares = await this.recoverEncryptedBackupByWallet({
+            accountAddress,
+            password,
+            walletOperation,
+            walletMetadata,
+            backupInfo
+        });
+        if (!recoveredShares || recoveredShares.length === 0) {
+            throw new Error(errorMessage);
         }
+        return recoveredShares;
     }
-    async recoverEncryptedBackupByWallet({ accountAddress, password, walletOperation, shareCount = undefined, storeRecoveredShares = true }) {
-        var _wallet_externalServerKeySharesBackupInfo;
+    async recoverEncryptedBackupByWallet({ accountAddress, password, walletOperation, shareCount = undefined, walletMetadata, backupInfo }) {
         this.ensureApiClientAuthenticated();
-        let wallet = this.walletMap[accountAddress];
-        if (!wallet) {
-            const fetchedWallet = await this.getWalletByAddress(accountAddress);
-            if (!fetchedWallet) {
-                throw new Error(`Wallet not found for address 1: ${accountAddress}`);
-            }
-            wallet = fetchedWallet;
-        }
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const walletId = walletMetadata.walletId;
+        const thresholdSignatureScheme = walletMetadata.thresholdSignatureScheme;
+        const externalServerKeySharesBackupInfo = backupInfo != null ? backupInfo : await this.resolveBackupInfo(walletMetadata);
         // PII: intentionally omitting full wallet object (contains key share info)
         this.logger.debug(`recoverEncryptedBackupByWallet wallet: ${walletOperation}`, {
-            walletId: wallet.walletId,
-            chainName: wallet.chainName
+            walletId
         });
         const { shares } = this.recoverStrategy({
-            externalServerKeySharesBackupInfo: wallet.externalServerKeySharesBackupInfo,
-            thresholdSignatureScheme: wallet.thresholdSignatureScheme,
+            externalServerKeySharesBackupInfo,
+            thresholdSignatureScheme,
             walletOperation,
             shareCount
         });
@@ -1294,13 +1444,13 @@ class DynamicWalletClient {
             return [];
         }
         const data = await this.apiClient.recoverEncryptedBackupByWallet({
-            walletId: wallet.walletId,
+            walletId,
             externalKeyShareIds: dynamicKeyShareIds,
             requiresSignedSessionId: false
         });
         const dynamicKeyShares = data.keyShares.filter((keyShare)=>keyShare.encryptedAccountCredential !== null && keyShare.backupLocation === core$1.BackupLocation.DYNAMIC);
-        var _wallet_externalServerKeySharesBackupInfo_passwordEncrypted;
-        const isPasswordEncrypted = (_wallet_externalServerKeySharesBackupInfo_passwordEncrypted = (_wallet_externalServerKeySharesBackupInfo = wallet.externalServerKeySharesBackupInfo) == null ? void 0 : _wallet_externalServerKeySharesBackupInfo.passwordEncrypted) != null ? _wallet_externalServerKeySharesBackupInfo_passwordEncrypted : false;
+        var _externalServerKeySharesBackupInfo_passwordEncrypted;
+        const isPasswordEncrypted = (_externalServerKeySharesBackupInfo_passwordEncrypted = externalServerKeySharesBackupInfo == null ? void 0 : externalServerKeySharesBackupInfo.passwordEncrypted) != null ? _externalServerKeySharesBackupInfo_passwordEncrypted : false;
         if (isPasswordEncrypted && !password) {
             throw new Error('Password is required for decryption but not provided. This backup was encrypted with a password.');
         }
@@ -1308,103 +1458,37 @@ class DynamicWalletClient {
                 keyShare: keyShare.encryptedAccountCredential,
                 password: password != null ? password : this.environmentId
             })));
-        if (storeRecoveredShares) {
-            this.walletMap[accountAddress] = _extends({}, this.walletMap[accountAddress], {
-                externalServerKeyShares: mergeUniqueKeyShares(this.walletMap[accountAddress].externalServerKeyShares || [], decryptedKeyShares)
-            });
-        }
         return decryptedKeyShares;
     }
-    async exportExternalServerKeyShares({ accountAddress, password }) {
+    async exportExternalServerKeyShares({ accountAddress, password, walletMetadata }) {
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const backupInfo = await this.resolveBackupInfo(walletMetadata);
         await this.verifyPassword({
             accountAddress,
-            password
+            password,
+            walletMetadata,
+            backupInfo
         });
         const externalServerKeyShares = await this.getExternalServerKeyShares({
             accountAddress,
-            password
+            password,
+            walletMetadata,
+            backupInfo
         });
         return externalServerKeyShares;
     }
     /**
-   * Helper function to check if the required wallet fields are present and valid
-   * @param accountAddress - The account address of the wallet to check
-   * @param walletOperation - The wallet operation that determines required fields
-   * @returns boolean indicating if wallet needs to be re-fetched and restored from server
-   */ async checkWalletFields({ accountAddress, walletOperation = core$1.WalletOperation.REACH_THRESHOLD, shareCount }) {
-        var _existingWallet_externalServerKeyShares;
-        let keyshareCheck = false;
-        let walletCheck = false;
-        let thresholdSignatureSchemeCheck = false;
-        let derivationPathCheck = false;
-        // check if wallet exists
-        const existingWallet = this.walletMap[accountAddress];
-        if (existingWallet) {
-            walletCheck = true;
-        }
-        // check if threshold signature scheme exists
-        if (existingWallet == null ? void 0 : existingWallet.thresholdSignatureScheme) {
-            thresholdSignatureSchemeCheck = true;
-        }
-        // check if derivation path exists
-        if ((existingWallet == null ? void 0 : existingWallet.derivationPath) || (existingWallet == null ? void 0 : existingWallet.derivationPath) === '') {
-            derivationPathCheck = true;
-        }
-        // check if wallet already exists with sufficient keyshares
-        if (existingWallet) {
-            var _existingWallet_externalServerKeyShares1;
-            const { shares } = this.recoverStrategy({
-                externalServerKeySharesBackupInfo: existingWallet.externalServerKeySharesBackupInfo || {
-                    backups: getExternalServerKeyShareBackupInfo()
-                },
-                thresholdSignatureScheme: existingWallet.thresholdSignatureScheme,
-                walletOperation,
-                shareCount
-            });
-            const { dynamic: requiredDynamicKeyShareIds = [] } = shares;
-            const { external: requiredExternalKeyShareIds = [] } = shares;
-            // Check if we have enough shares from any backup location
-            const totalRequiredShares = requiredDynamicKeyShareIds.length + requiredExternalKeyShareIds.length;
-            // Check if we have the required shares either loaded OR available in backup
-            const hasLoadedShares = totalRequiredShares <= (((_existingWallet_externalServerKeyShares1 = existingWallet.externalServerKeyShares) == null ? void 0 : _existingWallet_externalServerKeyShares1.length) || 0);
-            // Check if backup contains the specific required share IDs
-            const hasBackupShares = existingWallet.externalServerKeySharesBackupInfo && (()=>{
-                const backupShares = existingWallet.externalServerKeySharesBackupInfo.backups.dynamic;
-                const allRequiredIds = [
-                    ...requiredDynamicKeyShareIds,
-                    ...requiredExternalKeyShareIds
-                ];
-                return allRequiredIds.every((requiredId)=>backupShares.some((backupShare)=>backupShare.externalKeyShareId === requiredId));
-            })();
-            if (hasLoadedShares || hasBackupShares) {
-                keyshareCheck = true;
-            }
-        }
-        const result = walletCheck && thresholdSignatureSchemeCheck && keyshareCheck && derivationPathCheck;
-        this.logger.debug('Wallet checks:', {
-            walletCheck,
-            thresholdSignatureSchemeCheck,
-            keyshareCheck,
-            derivationPathCheck,
-            existingWallet: !!existingWallet,
-            keySharesLength: existingWallet == null ? void 0 : (_existingWallet_externalServerKeyShares = existingWallet.externalServerKeyShares) == null ? void 0 : _existingWallet_externalServerKeyShares.length,
-            result
-        });
-        return result;
-    }
-    /**
    * verifyPassword attempts to recover and decrypt a single client key share using the provided password.
    * If successful, the key share is encrypted with the new password. This method solely performs the recovery
    * and decryption without storing the restored key shares. If unsuccessful, it throws an error.
-   */ async verifyPassword({ accountAddress, password = undefined }) {
-        await this.getWallet({
-            accountAddress,
-            password,
-            walletOperation: core$1.WalletOperation.NO_OPERATION
-        });
+   */ async verifyPassword({ accountAddress, password = undefined, walletMetadata, backupInfo }) {
+        this.assertAddressMatchesMetadata(accountAddress, walletMetadata);
+        const resolvedBackupInfo = backupInfo != null ? backupInfo : await this.resolveBackupInfo(walletMetadata);
         if (await this.requiresPasswordForOperation({
             accountAddress,
-            walletOperation: core$1.WalletOperation.NO_OPERATION
+            walletOperation: core$1.WalletOperation.NO_OPERATION,
+            walletMetadata,
+            backupInfo: resolvedBackupInfo
         }) && !password) {
             throw new Error('Password is required for operation but not provided');
         }
@@ -1412,9 +1496,7 @@ class DynamicWalletClient {
         if (!password) {
             return;
         }
-        const { backups } = await this.getWalletExternalServerKeyShareBackupInfo({
-            accountAddress
-        });
+        const { backups } = resolvedBackupInfo;
         const { dynamic: dynamicKeyShareIds = [] } = backups;
         const { external: externalKeyShareIds = [] } = backups;
         // Check if we have any shares available (DYNAMIC or EXTERNAL)
@@ -1422,180 +1504,105 @@ class DynamicWalletClient {
             throw new Error('No key shares found');
         }
         try {
-            // Recover and store shares to unlock the wallet (storeRecoveredShares defaults to true)
             await this.recoverEncryptedBackupByWallet({
                 accountAddress,
                 password,
-                walletOperation: core$1.WalletOperation.NO_OPERATION
+                walletOperation: core$1.WalletOperation.NO_OPERATION,
+                walletMetadata,
+                backupInfo: resolvedBackupInfo
             });
         } catch (error) {
             this.logger.error('Error in verifying password', error);
-            throw new Error('Incorrect password');
+            // We can't distinguish wrong-password from stale-metadata without a
+            // server-side backupInfo lookup (fetchWalletMetadata returns identity
+            // only). Surface both possibilities so customers know where to look.
+            throw new Error('Failed to verify password. Either the password is incorrect, or the cached `walletMetadata.externalServerKeySharesBackupInfo` is stale ' + '(merge the `backupInfo` returned from updatePassword/refreshWalletAccountShares/reshare into your cached walletMetadata).');
         }
     }
-    async isPasswordEncrypted({ accountAddress }) {
-        const externalServerKeySharesBackupInfo = await this.getWalletExternalServerKeyShareBackupInfo({
-            accountAddress
+    async isPasswordEncrypted({ accountAddress, walletMetadata, backupInfo }) {
+        const externalServerKeySharesBackupInfo = backupInfo != null ? backupInfo : await this.getWalletExternalServerKeyShareBackupInfo({
+            walletMetadata
         });
         return externalServerKeySharesBackupInfo == null ? void 0 : externalServerKeySharesBackupInfo.passwordEncrypted;
     }
     /**
    * check if the operation requires a password
-   */ async requiresPasswordForOperation({ accountAddress, walletOperation = core$1.WalletOperation.REACH_THRESHOLD }) {
+   */ async requiresPasswordForOperation({ accountAddress, walletOperation = core$1.WalletOperation.REACH_THRESHOLD, walletMetadata, backupInfo }) {
         const isEncrypted = await this.isPasswordEncrypted({
-            accountAddress
+            accountAddress,
+            walletMetadata,
+            backupInfo
         });
         if (!isEncrypted) {
             return false;
         }
         return this.requiresRestoreBackupSharesForOperation({
             accountAddress,
-            walletOperation
+            walletOperation,
+            walletMetadata,
+            backupInfo
         });
     }
     /**
    * check if the operation requires restoring backup shares
-   */ async requiresRestoreBackupSharesForOperation({ accountAddress, walletOperation = core$1.WalletOperation.REACH_THRESHOLD }) {
-        const externalServerKeySharesBackupInfo = await this.getWalletExternalServerKeyShareBackupInfo({
-            accountAddress
+   */ async requiresRestoreBackupSharesForOperation({ accountAddress, walletOperation = core$1.WalletOperation.REACH_THRESHOLD, walletMetadata, backupInfo }) {
+        const externalServerKeySharesBackupInfo = backupInfo != null ? backupInfo : await this.getWalletExternalServerKeyShareBackupInfo({
+            walletMetadata
         });
-        const externalServerKeyShares = this.walletMap[accountAddress].externalServerKeyShares || [];
+        const thresholdSignatureScheme = walletMetadata.thresholdSignatureScheme;
         if (walletOperation === core$1.WalletOperation.REACH_ALL_PARTIES || walletOperation === core$1.WalletOperation.REFRESH || walletOperation === core$1.WalletOperation.RESHARE) {
             return true;
         }
         const { shares, requiredShareCount } = this.recoverStrategy({
             externalServerKeySharesBackupInfo,
-            thresholdSignatureScheme: this.walletMap[accountAddress].thresholdSignatureScheme,
+            thresholdSignatureScheme,
             walletOperation
         });
         const dynamicKeyShareIds = shares[core$1.BackupLocation.DYNAMIC] || [];
         const externalKeyShareIds = shares[core$1.BackupLocation.EXTERNAL] || [];
-        // Check if we have enough shares from either location
-        const totalAvailableShares = externalServerKeyShares.length + dynamicKeyShareIds.length + externalKeyShareIds.length;
+        const totalAvailableShares = dynamicKeyShareIds.length + externalKeyShareIds.length;
         if (totalAvailableShares >= requiredShareCount) {
             return false;
         }
         return true;
     }
-    async getWalletExternalServerKeyShareBackupInfo({ accountAddress }) {
-        var _wallet_externalServerKeySharesBackupInfo_backups_BackupLocation_DYNAMIC, _wallet_externalServerKeySharesBackupInfo_backups, _wallet_externalServerKeySharesBackupInfo, _user_verifiedCredentials;
+    async getWalletExternalServerKeyShareBackupInfo({ walletMetadata }) {
         this.ensureApiClientAuthenticated();
-        let wallet = this.walletMap[accountAddress];
-        if (!wallet) {
-            const fetchedWallet = await this.getWalletByAddress(accountAddress);
-            if (!fetchedWallet) {
-                throw new Error(`Wallet not found for address 2: ${accountAddress}`);
-            }
-            wallet = fetchedWallet;
-        }
-        // Return existing backup info if it exists
-        if (((_wallet_externalServerKeySharesBackupInfo = wallet.externalServerKeySharesBackupInfo) == null ? void 0 : (_wallet_externalServerKeySharesBackupInfo_backups = _wallet_externalServerKeySharesBackupInfo.backups) == null ? void 0 : (_wallet_externalServerKeySharesBackupInfo_backups_BackupLocation_DYNAMIC = _wallet_externalServerKeySharesBackupInfo_backups[core$1.BackupLocation.DYNAMIC]) == null ? void 0 : _wallet_externalServerKeySharesBackupInfo_backups_BackupLocation_DYNAMIC.length) > 0) {
-            return wallet.externalServerKeySharesBackupInfo;
-        }
-        // Get backup info from server
-        const user = await this.apiClient.getUser(uuid.v4());
-        const walletData = (_user_verifiedCredentials = user.verifiedCredentials) == null ? void 0 : _user_verifiedCredentials.find((vc)=>{
-            var _vc_address;
-            return ((_vc_address = vc.address) == null ? void 0 : _vc_address.toLowerCase()) === accountAddress.toLowerCase();
-        });
-        return getExternalServerKeyShareBackupInfo({
-            walletProperties: walletData == null ? void 0 : walletData.walletProperties
-        });
-    }
-    async getWallet({ accountAddress, walletOperation = core$1.WalletOperation.NO_OPERATION, shareCount = undefined, password = undefined }) {
-        try {
-            this.ensureApiClientAuthenticated();
-            const existingWalletCheck = await this.checkWalletFields({
-                accountAddress,
-                walletOperation,
-                shareCount
-            });
-            if (existingWalletCheck) {
-                this.logger.debug(`Wallet ${accountAddress} already exists`);
-                return this.walletMap[accountAddress];
-            }
-            const wallet = await this.getWalletByAddress(accountAddress);
-            if (!wallet) {
-                throw new Error(`Wallet not found for address 3: ${accountAddress}`);
-            }
-            // PII: intentionally omitting full wallet object (contains key share info)
-            this.logger.debug('Restoring wallet', {
-                walletId: wallet.walletId,
-                chainName: wallet.chainName
-            });
-            // The wallet is already processed, so we can use it directly
-            this.walletMap[accountAddress] = wallet;
-            if (walletOperation !== core$1.WalletOperation.NO_OPERATION && await this.requiresRestoreBackupSharesForOperation({
-                accountAddress,
-                walletOperation
-            })) {
-                const decryptedKeyShares = await this.recoverEncryptedBackupByWallet({
-                    accountAddress,
-                    password: password != null ? password : this.environmentId,
-                    walletOperation: walletOperation,
-                    shareCount
-                });
-                // PII: intentionally omitting decryptedKeyShares (contains key material)
-                this.logger.debug('[DynamicWaasWalletClient] Recovered backup', {
-                    shareCount: decryptedKeyShares == null ? void 0 : decryptedKeyShares.length
-                });
-            }
-            // externalServerKeyShares
-            const walletCount = Object.keys(this.walletMap).length;
-            if (walletCount === 0) {
-                throw new Error('No wallets found');
-            }
-            // Return the only wallet if there's just one
-            if (walletCount === 1) {
-                return Object.values(this.walletMap)[0];
-            }
-            return this.walletMap[accountAddress];
-        } catch (error) {
-            this.logger.error('Error in getWallet', error);
-            throw error;
-        }
+        return this.resolveBackupInfo(walletMetadata);
     }
     /**
-   * Get a single wallet by address
-   * First tries the efficient getWaasWalletByAddress endpoint, falls back to getUser() if not available
+   * Get a single wallet by address.
+   * First tries the efficient `getWaasWalletByAddress` endpoint, falls back to
+   * `getUser()` if not available.
+   *
+   * Note: the `getWaasWalletByAddress` endpoint returns wallet identity only
+   * — it does not include keyShare pointer metadata, so the byAddress path
+   * leaves `externalServerKeySharesBackupInfo` `undefined`. Operations that
+   * need it (sign with auto-recovery, password verification, refresh,
+   * reshare, updatePassword) will throw on a result obtained via this path.
+   * The `getUser()` fallback populates `externalServerKeySharesBackupInfo`
+   * from `walletProperties.keyShares`.
+   *
+   * Prefer `fetchWalletMetadata(accountAddress)` for identity-only lookups.
    */ async getWalletByAddress(accountAddress) {
-        // Return cached wallet if available
-        if (this.walletMap[accountAddress]) {
-            return this.walletMap[accountAddress];
-        }
         this.ensureApiClientAuthenticated();
-        // Try getting single wallet by address first
         try {
-            var _walletResponse_wallet;
             const walletResponse = await this.apiClient.getWaasWalletByAddress({
                 walletAddress: accountAddress
             });
-            const walletProperties = {
+            return {
                 walletId: walletResponse.wallet.walletId,
                 chainName: walletResponse.wallet.chainName,
                 accountAddress: walletResponse.wallet.accountAddress,
                 externalServerKeyShares: [],
                 derivationPath: walletResponse.wallet.derivationPath,
-                thresholdSignatureScheme: walletResponse.wallet.thresholdSignatureScheme,
-                externalServerKeySharesBackupInfo: getExternalServerKeyShareBackupInfo({
-                    walletProperties: {
-                        // @ts-expect-error TODO: update response to get key shares
-                        keyShares: ((_walletResponse_wallet = walletResponse.wallet) == null ? void 0 : _walletResponse_wallet.keyShares) || [],
-                        thresholdSignatureScheme: walletResponse.wallet.thresholdSignatureScheme,
-                        derivationPath: walletResponse.wallet.derivationPath
-                    }
-                })
+                thresholdSignatureScheme: walletResponse.wallet.thresholdSignatureScheme
             };
-            // Cache the wallet
-            this.walletMap[accountAddress] = walletProperties;
-            return walletProperties;
         } catch (error) {
             var _error_response;
-            // If the new endpoint doesn't exist (404 or not implemented), fall back to getUser()
             if ((error == null ? void 0 : (_error_response = error.response) == null ? void 0 : _error_response.status) === 404 || (error == null ? void 0 : error.code) === 'ERR_BAD_REQUEST') {
                 var _user_verifiedCredentials, _wallet_walletProperties, _wallet_walletProperties1;
                 this.logger.debug('getWaasWalletByAddress endpoint not available, falling back to getUser()');
-                // Fallback to getUser() approach
                 const user = await this.apiClient.getUser(uuid.v4());
                 const wallet = (_user_verifiedCredentials = user.verifiedCredentials) == null ? void 0 : _user_verifiedCredentials.find((vc)=>{
                     var _vc_address;
@@ -1605,9 +1612,9 @@ class DynamicWalletClient {
                     return null;
                 }
                 var _wallet_walletProperties_derivationPath;
-                const walletProperties = {
+                return {
                     walletId: wallet.id,
-                    chainName: wallet.chain,
+                    chainName: core$1.verifiedCredentialNameToChainEnum[wallet.chain],
                     accountAddress: wallet.address,
                     externalServerKeyShares: [],
                     derivationPath: (_wallet_walletProperties_derivationPath = (_wallet_walletProperties = wallet.walletProperties) == null ? void 0 : _wallet_walletProperties.derivationPath) != null ? _wallet_walletProperties_derivationPath : undefined,
@@ -1616,9 +1623,6 @@ class DynamicWalletClient {
                         walletProperties: wallet.walletProperties || {}
                     })
                 };
-                // Cache the wallet
-                this.walletMap[accountAddress] = walletProperties;
-                return walletProperties;
             }
             throw error;
         }
@@ -1633,8 +1637,8 @@ class DynamicWalletClient {
         var _user_verifiedCredentials;
         const verifiedCredentials = (_user_verifiedCredentials = user.verifiedCredentials) != null ? _user_verifiedCredentials : [];
         const waasWallets = verifiedCredentials.filter((vc)=>vc.walletName === 'dynamicwaas' && !!vc.address && !!vc.chain);
-        const wallets = waasWallets.map((vc)=>{
-            var _this_walletMap_vc_address, _vc_walletProperties, _vc_walletProperties1;
+        return waasWallets.map((vc)=>{
+            var _vc_walletProperties, _vc_walletProperties1;
             var _vc_walletProperties_thresholdSignatureScheme;
             return {
                 walletId: vc.id,
@@ -1643,49 +1647,13 @@ class DynamicWalletClient {
                 externalServerKeySharesBackupInfo: getExternalServerKeyShareBackupInfo({
                     walletProperties: vc.walletProperties
                 }),
-                externalServerKeyShares: ((_this_walletMap_vc_address = this.walletMap[vc.address]) == null ? void 0 : _this_walletMap_vc_address.externalServerKeyShares) || [],
+                externalServerKeyShares: [],
                 derivationPath: (_vc_walletProperties = vc.walletProperties) == null ? void 0 : _vc_walletProperties.derivationPath,
                 thresholdSignatureScheme: (_vc_walletProperties_thresholdSignatureScheme = (_vc_walletProperties1 = vc.walletProperties) == null ? void 0 : _vc_walletProperties1.thresholdSignatureScheme) != null ? _vc_walletProperties_thresholdSignatureScheme : core$1.ThresholdSignatureScheme.TWO_OF_TWO
             };
         });
-        this.walletMap = wallets.reduce((acc, wallet)=>{
-            acc[wallet.accountAddress] = wallet;
-            return acc;
-        }, {});
-        return wallets;
-    }
-    /**
-   * Helper method to initialize or update a wallet entry in the walletMap.
-   * This provides a consistent way to set up wallet properties across different operations.
-   * @param accountAddress - The account address for the wallet
-   * @param walletId - The wallet ID
-   * @param chainName - The chain name (e.g., 'BTC', 'EVM')
-   * @param thresholdSignatureScheme - The threshold signature scheme
-   * @param derivationPath - Optional derivation path for the wallet
-   * @param additionalProps - Optional additional properties to merge into the wallet entry
-   */ initializeWalletMapEntry({ accountAddress, walletId, chainName, thresholdSignatureScheme, derivationPath, additionalProps = {} }) {
-        this.walletMap[accountAddress] = _extends({}, this.walletMap[accountAddress], {
-            accountAddress,
-            walletId,
-            chainName,
-            thresholdSignatureScheme
-        }, derivationPath ? {
-            derivationPath
-        } : {}, {
-            externalServerKeySharesBackupInfo: getExternalServerKeyShareBackupInfo()
-        }, additionalProps);
-        // PII: intentionally omitting walletMap (contains key share data for all wallets)
-        this.logger.debug('walletMap initialized for wallet', {
-            context: {
-                accountAddress,
-                walletId,
-                chainName
-            }
-        });
     }
     constructor({ environmentId, baseApiUrl, baseMPCRelayApiUrl, debug, forwardMPCClient, enableMPCAccelerator = true, logger: logger$1 }){
-        this.walletMap = {} // todo: store in session storage
-        ;
         this.isApiClientAuthenticated = false;
         this.forwardMPCEnabled = true;
         if (logger$1) {
@@ -1910,6 +1878,51 @@ const revokeDelegation = async (client, walletId)=>{
     }
 };
 
+function decryptAesGcm(key, ivB64, ctB64, tagB64) {
+    const iv = Buffer.from(ivB64, 'base64url');
+    const ciphertext = Buffer.from(ctB64, 'base64url');
+    const tag = Buffer.from(tagB64, 'base64url');
+    const decipher = crypto$1.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    const updateResult = decipher.update(ciphertext);
+    const finalResult = decipher.final();
+    const plaintext = Buffer.concat([
+        updateResult,
+        finalResult
+    ]);
+    return plaintext;
+}
+function rsaOaepDecryptEk(privateKeyPem, ekB64) {
+    return crypto$1.privateDecrypt({
+        key: privateKeyPem,
+        oaepHash: 'sha256',
+        padding: crypto$1.constants.RSA_PKCS1_OAEP_PADDING
+    }, Buffer.from(ekB64, 'base64url'));
+}
+function decryptDelegatedWebhookData({ privateKeyPem, encryptedDelegatedKeyShare, encryptedWalletApiKey }) {
+    try {
+        const shareKey = rsaOaepDecryptEk(privateKeyPem, encryptedDelegatedKeyShare.ek);
+        const walletApiKeyKey = rsaOaepDecryptEk(privateKeyPem, encryptedWalletApiKey.ek);
+        const decryptedDelegatedShare = decryptAesGcm(shareKey, encryptedDelegatedKeyShare.iv, encryptedDelegatedKeyShare.ct, encryptedDelegatedKeyShare.tag);
+        const decryptedWalletApiKey = decryptAesGcm(walletApiKeyKey, encryptedWalletApiKey.iv, encryptedWalletApiKey.ct, encryptedWalletApiKey.tag);
+        const decryptedWalletApiKeyString = decryptedWalletApiKey.toString('utf8');
+        const decryptedDelegatedShareString = decryptedDelegatedShare.toString('utf8');
+        const decryptedDelegatedShareObject = JSON.parse(decryptedDelegatedShareString);
+        if (!decryptedDelegatedShareObject) {
+            throw new Error('Failed to decrypt delegated share');
+        }
+        if (!decryptedWalletApiKeyString) {
+            throw new Error('Failed to decrypt wallet API key');
+        }
+        return {
+            decryptedDelegatedShare: decryptedDelegatedShareObject,
+            decryptedWalletApiKey: decryptedWalletApiKeyString
+        };
+    } catch (error) {
+        throw new Error('Failed to decrypt delegated webhook data: ' + error);
+    }
+}
+
 Object.defineProperty(exports, "SOLANA_RPC_URL", {
   enumerable: true,
   get: function () { return core$1.SOLANA_RPC_URL; }
@@ -1931,6 +1944,7 @@ exports.base64ToBytes = base64ToBytes;
 exports.bytesToBase64 = bytesToBase64;
 exports.createDelegatedWalletClient = createDelegatedWalletClient;
 exports.createLogError = createLogError;
+exports.decryptDelegatedWebhookData = decryptDelegatedWebhookData;
 exports.delegatedSignMessage = delegatedSignMessage;
 exports.ensureBase64Padding = ensureBase64Padding;
 exports.formatEvmMessage = formatEvmMessage;