@dynamic-labs-wallet/browser 1.1.34 → 1.1.36

package/index.cjs

@@ -2600,6 +2600,45 @@ const classifyOne = (error)=>{
     }
     return fallback;
 };
+/** The HTTP status and backend code of one link in a `cause` chain, or `undefined` when it is not a rejected request. */ const httpFieldsOf = (error)=>{
+    if (error instanceof axios.AxiosError && error.response) {
+        const errorCode = core.extractServerErrorCode(error);
+        return _extends({
+            httpStatus: error.response.status
+        }, errorCode ? {
+            errorCode
+        } : {});
+    }
+    const status = getWalletApiErrorStatus(error);
+    if (status === undefined) return undefined;
+    const { code } = error;
+    return _extends({
+        httpStatus: status
+    }, typeof code === 'string' ? {
+        errorCode: code
+    } : {});
+};
+/**
+ * The fields a failure is filtered by: its class, the HTTP status and the
+ * backend's own code when a request was rejected. Walks the `cause` chain so a
+ * chain client's wrapper does not hide the API error beneath it. Scalars only,
+ * so nothing from a response body can carry key material into a log.
+ */ const describeErrorForLog = (error)=>{
+    const errorName = error instanceof Error ? error.name : typeof error;
+    let current = error;
+    for(let depth = 0; current !== undefined && current !== null && depth < MAX_CAUSE_DEPTH; depth += 1){
+        const httpFields = httpFieldsOf(current);
+        if (httpFields) return _extends({
+            errorName
+        }, httpFields);
+        const next = current instanceof Error ? current.cause : undefined;
+        if (next === current) break;
+        current = next;
+    }
+    return {
+        errorName
+    };
+};
 /**
  * Decides how an operation failure reaches the Datadog logger, whose signature
  * is `(message, context, error)`.
@@ -3035,9 +3074,10 @@ const createDynamicOnlyDistribution = ({ allShares })=>({
    * @param accountAddress - The wallet address
    * @param operation - The operation type (must be a valid SignQueueOperation)
    * @param callback - The sign operation to execute
+   * @param options - Optional diagnostics attached to timeout logs
    * @throws Error if operation is not a valid sign queue operation
    * @returns Promise resolving to the sign result
-   */ static async queueSignOperation(accountAddress, operation, callback) {
+   */ static async queueSignOperation(accountAddress, operation, callback, options) {
         accountAddress = normalizeAddress(accountAddress);
         // Runtime validation to catch any type assertion bypasses
         if (!isSignQueueOperation(operation)) {
@@ -3060,6 +3100,13 @@ const createDynamicOnlyDistribution = ({ allShares })=>({
         let currentPhase = 'queued';
         let phaseStartedAt = Date.now();
         const signDetails = {};
+        const enclaveContext = ()=>{
+            var _options_getEnclaveSnapshot;
+            const forwardMpcEnclave = options == null ? void 0 : (_options_getEnclaveSnapshot = options.getEnclaveSnapshot) == null ? void 0 : _options_getEnclaveSnapshot.call(options);
+            return forwardMpcEnclave ? {
+                forwardMpcEnclave
+            } : {};
+        };
         // The task keeps running after the queue timeout rejects `add()`, so keep
         // a reference to observe how it eventually settles.
         let taskPromise;
@@ -3115,7 +3162,7 @@ const createDynamicOnlyDistribution = ({ allShares })=>({
                     signQueuePending: signQueue.pending,
                     signQueueSize: signQueue.size,
                     recoveryInProgress: this.isRecoveryInProgress(accountAddress)
-                }, signDetails),
+                }, enclaveContext(), signDetails),
                 level: 'warn'
             });
             // The caller already saw an error; record how the orphaned ceremony
@@ -3133,7 +3180,7 @@ const createDynamicOnlyDistribution = ({ allShares })=>({
                         operation,
                         outcome: 'resolved',
                         settledMs: Date.now() - timedOutAt
-                    }, signDetails),
+                    }, enclaveContext(), signDetails),
                     level: 'warn'
                 });
             }, (lateError)=>{
@@ -3146,7 +3193,7 @@ const createDynamicOnlyDistribution = ({ allShares })=>({
                         outcome: 'rejected',
                         settledMs: Date.now() - timedOutAt,
                         causes: describeCauseChain(lateError)
-                    }, signDetails),
+                    }, enclaveContext(), signDetails),
                     level: 'warn'
                 });
             });
@@ -3238,6 +3285,46 @@ const createDynamicOnlyDistribution = ({ allShares })=>({
 /** 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 FLAP_WINDOW_MS = 60000;
+// Bounds memory on a socket that flaps indefinitely; the count saturates here.
+const MAX_TRACKED_DISCONNECTS = 50;
+// The iframe shares one socket across every chain client; one history per socket.
+const readers = new WeakMap();
+/**
+ * Starts recording enclave disconnects and returns a reader for the current
+ * state. Idempotent per client: call it right after creating the socket (before
+ * `connect()`) so startup disconnects are kept, and later calls reuse the same
+ * history instead of stacking listeners.
+ */ const trackForwardMpcEnclave = (client)=>{
+    const existing = readers.get(client);
+    if (existing) {
+        return existing;
+    }
+    const disconnects = [];
+    client.on('disconnected', (closeCode)=>{
+        disconnects.push({
+            at: Date.now(),
+            closeCode
+        });
+        if (disconnects.length > MAX_TRACKED_DISCONNECTS) {
+            disconnects.shift();
+        }
+    });
+    const reader = ()=>{
+        const now = Date.now();
+        const last = disconnects.at(-1);
+        return _extends({
+            connected: client.connected,
+            disconnectsLastMinute: disconnects.filter(({ at })=>now - at <= FLAP_WINDOW_MS).length
+        }, last && {
+            lastCloseCode: last.closeCode,
+            msSinceLastDisconnect: now - last.at
+        });
+    };
+    readers.set(client, reader);
+    return reader;
+};
+
 // A DYNAMIC backup can persist multiple shares (e.g. 2-of-3); the singular
 // externalKeyShareId is a fallback for older single-id shapes.
 const collectDynamicKeyShareIds = (locations)=>{
@@ -3766,6 +3853,11 @@ class DynamicWalletClient {
             });
         });
     }
+    queueSign(accountAddress, task) {
+        return WalletQueueManager.queueSignOperation(accountAddress, core.WalletOperation.SIGN_MESSAGE, task, {
+            getEnclaveSnapshot: this.enclaveSnapshot
+        });
+    }
     connectForwardMPC() {
         const forwardMPCConnectStartedAt = Date.now();
         this.apiClient.forwardMPCClient.connect().then(()=>{
@@ -4667,7 +4759,7 @@ class DynamicWalletClient {
         }
         // Note: the server signing party (wallet-service) selects the ed25519
         // protocol variant from its own persisted EAC, so it is NOT threaded here.
-        const serializedContext = context ? JSON.parse(JSON.stringify(context, (_key, value)=>typeof value === 'bigint' ? String(value) : value)) : undefined;
+        const serializedContext = context ? core.toJsonSafeContext(context) : undefined;
         const useHttpTransport = this.featureFlags[core.FEATURE_FLAGS.ENABLE_HTTP_WAAS_TRANSPORT] === true && this.featureFlags[core.FEATURE_FLAGS.ENABLE_HTTP_WAAS_TRANSPORT_SIGNMESSAGE] === true;
         const params = {
             walletId,
@@ -4690,6 +4782,45 @@ class DynamicWalletClient {
         })) : await this.apiClient.signMessage(params);
         return data;
     }
+    /**
+   * The server half of `signAndBroadcast`: asks Dynamic to open the signing rooms and returns the transaction record.
+   *
+   * @param params.walletId - The wallet that signs.
+   * @param params.shareSetId - Which of the wallet's key sets to use. Defaults to its active one.
+   * @param params.messages - The transaction once per fee attempt, in fee order, as the bytes to sign (RLP hex on EVM, message bytes on Solana). Not hashed.
+   * @param params.contexts - What each message does in readable form (chain, recipient, amount), one per message in the same order. Dynamic checks each against the wallet and its policies.
+   * @param params.broadcastOptions - Solana send settings: other required signers' signatures, and skipping the pre-send dry run.
+   * @param params.roomIds - Signing rooms you already opened, one per message. Send all or none; Dynamic opens them when omitted.
+   * @param params.requestedCertainty - How sure to be before calling it confirmed: `fast`, `safe` or `final`, or `chain:` plus a chain-specific value. Defaults to `safe`.
+   * @param params.externalReference - Your own label, returned on every event. Not unique.
+   * @param params.idempotencyKey - Makes a retry safe: the same key replays the stored answer instead of sending twice.
+   * @param params.mfaToken - Proof of the user's multi-factor check, when the wallet needs one.
+   * @param params.elevatedAccessToken - Proof of a recent re-login, when the wallet needs one.
+   * @param params.approvalQuorum - Approvers' consent for a governed wallet, sent on the retry after `intent_required`.
+   * @param params.onError - Called with the failure's message, never the raw error.
+   * @param params.dynamicRequestId - Id of this one request, to match client and server logs.
+   * @param params.traceContext - Ties this call's logs to the server's, across retries. Created when omitted.
+   */ async serverSignAndBroadcast({ walletId, shareSetId, contexts, broadcastOptions, messages, roomIds, requestedCertainty, externalReference, idempotencyKey, mfaToken, elevatedAccessToken, approvalQuorum, onError, dynamicRequestId, traceContext }) {
+        // Opens one signing room per message, unless `roomIds` names them, and returns the transaction record.
+        return await this.apiClient.signAndBroadcast({
+            walletId,
+            shareSetId,
+            contexts: contexts.map((context)=>core.toJsonSafeContext(context)),
+            broadcastOptions,
+            messages,
+            roomIds,
+            isFormatted: false,
+            requestedCertainty,
+            externalReference,
+            idempotencyKey,
+            mfaToken,
+            elevatedAccessToken,
+            approvalQuorum,
+            onError,
+            dynamicRequestId,
+            traceContext
+        });
+    }
     prepareMessageForForwardMPC({ chainName, message, formattedMessage, signingAlgo, isFormatted }) {
         // BIP340 hash unwrap MUST come first. When `isFormatted=true`, callers wrap
         // the payload in a `MessageHash`; the direct-MPC path then reads
@@ -4778,7 +4909,7 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async clientSign({ chainName, message, roomId: initialRoomId, keyShare, derivationPath, isFormatted, dynamicRequestId, traceContext, bitcoinConfig, variant, refreshRoom, onForwardMpcFailure }) {
+    async clientSign({ chainName, message, roomId: initialRoomId, keyShare, derivationPath, isFormatted, dynamicRequestId, traceContext, bitcoinConfig, variant, refreshRoom, skipForwardMPC, onForwardMpcFailure }) {
         // Reassigned when forward MPC fails and we mint a fresh room for the
         // relay-based fallback below.
         let roomId = initialRoomId;
@@ -4806,7 +4937,7 @@ class DynamicWalletClient {
                 isFormatted
             }, this.getTraceContext(traceContext)));
             // Try forward MPC first if enabled, with fallback to relay-based signing on attestation failure
-            if (this.forwardMPCEnabled && !this.shouldSkipForwardMPC(chainName)) {
+            if (this.forwardMPCEnabled && !skipForwardMPC && !this.shouldSkipForwardMPC(chainName)) {
                 attemptedForwardMPCSign = true;
                 const forwardMPCStartedAt = Date.now();
                 try {
@@ -5115,7 +5246,7 @@ class DynamicWalletClient {
     }
     //todo: need to modify with imported flag
     async sign({ accountAddress, message, chainName, password = undefined, isFormatted = false, signedSessionId, mfaToken, elevatedAccessToken, context, approvalQuorum, onError, traceContext, bitcoinConfig }) {
-        return WalletQueueManager.queueSignOperation(accountAddress, core.WalletOperation.SIGN_MESSAGE, ({ reportPhase, reportDetails })=>this.internalSign({
+        return this.queueSign(accountAddress, ({ reportPhase, reportDetails })=>this.internalSign({
                 accountAddress,
                 message,
                 chainName,
@@ -5134,6 +5265,278 @@ class DynamicWalletClient {
             }));
     }
     /**
+   * Signs a transaction for Dynamic to broadcast, one signing ceremony per message. The signature stays on the server.
+   *
+   * @param params.accountAddress - The wallet's address.
+   * @param params.chainName - The wallet's chain, e.g. `EVM`.
+   * @param params.messages - The transaction once per fee attempt, in fee order, as the bytes to sign (RLP hex on EVM, message bytes on Solana). Not hashed.
+   * @param params.contexts - What each message does in readable form (chain, recipient, amount), one per message in the same order. Dynamic checks each against the wallet and its policies.
+   * @param params.broadcastOptions - Solana send settings: other required signers' signatures, and skipping the pre-send dry run.
+   * @param params.password - The wallet's backup password, if it has one.
+   * @param params.signedSessionId - The signed-in session, used to unlock the wallet's key share.
+   * @param params.mfaToken - Proof of the user's multi-factor check, when the wallet needs one.
+   * @param params.elevatedAccessToken - Proof of a recent re-login, when the wallet needs one.
+   * @param params.approvalQuorum - Approvers' consent for a governed wallet, sent on the retry after `intent_required`.
+   * @param params.requestedCertainty - How sure to be before calling it confirmed: `fast`, `safe` or `final`, or `chain:` plus a chain-specific value. Defaults to `safe`.
+   * @param params.externalReference - Your own label, returned on every event. Not unique.
+   * @param params.idempotencyKey - Makes a retry safe: the same key replays the stored answer instead of sending twice. A new one is made when omitted.
+   * @param params.onError - Called with the failure's message, never the raw error.
+   * @param params.traceContext - Ties this call's logs to the server's, across retries. Created when omitted.
+   * @returns The transaction record. A finished one comes back without signing again.
+   * @throws Error when `contexts` and `messages` differ in length.
+   */ async signAndBroadcast({ accountAddress, chainName, contexts, broadcastOptions, messages, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, approvalQuorum, requestedCertainty, externalReference, idempotencyKey = uuid.v4(), onError, traceContext }) {
+        // Each fee attempt is one message and one context; a mismatch is the caller's, so it is named here, before any ceremony.
+        if (messages.length === 0 || contexts.length !== messages.length) {
+            throw new Error(`Sign and broadcast needs one signing context per message, got ${contexts.length} contexts for ${messages.length} messages`);
+        }
+        return this.queueSign(accountAddress, ({ reportPhase })=>this.internalSignAndBroadcast({
+                accountAddress,
+                chainName,
+                contexts,
+                broadcastOptions,
+                messages,
+                password,
+                signedSessionId,
+                mfaToken,
+                elevatedAccessToken,
+                approvalQuorum,
+                requestedCertainty,
+                externalReference,
+                idempotencyKey,
+                onError,
+                traceContext,
+                onSignPhase: reportPhase
+            }));
+    }
+    /**
+   * Does the work of `signAndBroadcast` once it has its turn in the wallet queue: loads the wallet, asks Dynamic to open the rooms, then signs in each.
+   *
+   * Takes the same fields as `signAndBroadcast`.
+   *
+   * @param params.onSignPhase - Reports which step it is on, so the queue can tell which step used up the time.
+   */ async internalSignAndBroadcast({ accountAddress, chainName, contexts, broadcastOptions, messages, password, signedSessionId, mfaToken, elevatedAccessToken, approvalQuorum, requestedCertainty, externalReference, idempotencyKey, onError, traceContext, onSignPhase, staleShareRetry = false, roomIdRetry = false }) {
+        const dynamicRequestId = uuid.v4();
+        traceContext = core.withTraceId(traceContext);
+        let stage = 'prepareWallet';
+        let roomIdSource;
+        this.logger.info('[DynamicWaasWalletClient] Sign and broadcast started', _extends({
+            key: 'signAndBroadcast',
+            operation: 'start',
+            accountAddress,
+            chainName,
+            dynamicRequestId,
+            attemptCount: messages.length,
+            staleShareRetry,
+            roomIdRetry
+        }, this.getTraceContext(traceContext)));
+        try {
+            const { wallet, derivationPath, clientKeyShares, timings: { startedAt, passwordVerifiedAt, walletLoadedAt, sharesReadyAt } } = await this.prepareWalletForSign({
+                accountAddress,
+                password,
+                signedSessionId,
+                onSignPhase
+            });
+            stage = 'resolveCachedRoom';
+            onSignPhase == null ? void 0 : onSignPhase('resolveCachedRoom');
+            const roomIds = roomIdRetry ? undefined : await this.getCachedRoomsForSignAndBroadcast(wallet, accountAddress, chainName, messages.length, dynamicRequestId, traceContext);
+            roomIdSource = roomIds ? 'cache' : 'server';
+            const roomsResolvedAt = Date.now();
+            this.logSlowSignPreflight({
+                accountAddress,
+                chainName,
+                dynamicRequestId,
+                traceContext,
+                verifyPasswordMs: passwordVerifiedAt - startedAt,
+                getWalletMs: walletLoadedAt - passwordVerifiedAt,
+                ensureClientShareMs: sharesReadyAt - walletLoadedAt,
+                resolveCachedRoomMs: roomsResolvedAt - sharesReadyAt,
+                totalMs: roomsResolvedAt - startedAt
+            });
+            stage = 'serverSign';
+            onSignPhase == null ? void 0 : onSignPhase('serverSign');
+            const record = await this.serverSignAndBroadcast({
+                walletId: wallet.walletId,
+                shareSetId: wallet.shareSetId,
+                contexts,
+                broadcastOptions,
+                messages,
+                roomIds,
+                requestedCertainty,
+                externalReference,
+                idempotencyKey,
+                mfaToken,
+                elevatedAccessToken,
+                approvalQuorum,
+                onError,
+                dynamicRequestId,
+                traceContext
+            });
+            var _record_rooms;
+            const rooms = (_record_rooms = record.rooms) != null ? _record_rooms : [];
+            var _roomIds_length;
+            this.logger.info('[DynamicWaasWalletClient] Sign and broadcast accepted', _extends({
+                key: 'signAndBroadcast',
+                operation: 'accepted',
+                accountAddress,
+                chainName,
+                dynamicRequestId,
+                transactionId: record.transactionId,
+                transactionStatus: record.status,
+                attemptCount: messages.length,
+                roomIdSource,
+                roomsSent: (_roomIds_length = roomIds == null ? void 0 : roomIds.length) != null ? _roomIds_length : 0,
+                roomsReturned: rooms.length,
+                // A retry of an existing row names that row's rooms, not the ones just sent.
+                returnedRoomsMatchSent: roomIds ? roomIds.every((roomId, index)=>{
+                    var _rooms_index;
+                    return ((_rooms_index = rooms[index]) == null ? void 0 : _rooms_index.roomId) === roomId;
+                }) : undefined
+            }, this.getTraceContext(traceContext)));
+            // A retry of a finished request returns the record without rooms.
+            if (record.status !== 'pending_signature') {
+                return record;
+            }
+            if (rooms.length !== messages.length) {
+                throw new Error(`Expected ${messages.length} signing rooms, got ${rooms.length} for transaction ${record.transactionId}`);
+            }
+            stage = 'ceremony';
+            onSignPhase == null ? void 0 : onSignPhase('ceremony');
+            const ceremonies = Promise.all(rooms.map((room, index)=>this.clientSign({
+                    chainName,
+                    message: messages[index],
+                    roomId: room.roomId,
+                    keyShare: clientKeyShares[0],
+                    derivationPath,
+                    isFormatted: false,
+                    dynamicRequestId,
+                    traceContext,
+                    variant: wallet.variant,
+                    // Nothing mints a replacement room for a broadcast attempt.
+                    skipForwardMPC: true
+                })));
+            const getClientSignMismatch = this.trackClientSignMismatch(ceremonies, {
+                accountAddress,
+                chainName,
+                password,
+                signedSessionId,
+                mfaToken,
+                dynamicRequestId,
+                traceContext
+            });
+            try {
+                await ceremonies;
+            } catch (signError) {
+                stage = 'healAfterFailure';
+                await this.healAfterSignFailure({
+                    signError,
+                    clientSignMismatch: getClientSignMismatch(),
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    mfaToken,
+                    dynamicRequestId,
+                    traceContext
+                });
+                stage = 'ceremony';
+                throw signError;
+            }
+            this.logger.info('[DynamicWaasWalletClient] Client sign completed', _extends({
+                accountAddress,
+                chainName,
+                roomIds: rooms.map((room)=>room.roomId),
+                dynamicRequestId,
+                key: 'signAndBroadcast',
+                operation: 'clientSign'
+            }, this.getTraceContext(traceContext)));
+            return record;
+        } catch (error) {
+            const retryParams = {
+                accountAddress,
+                chainName,
+                contexts,
+                broadcastOptions,
+                messages,
+                password,
+                signedSessionId,
+                mfaToken,
+                elevatedAccessToken,
+                approvalQuorum,
+                requestedCertainty,
+                externalReference,
+                idempotencyKey,
+                onError,
+                traceContext,
+                onSignPhase
+            };
+            // The server rejected the local shares as stale before opening any room. Heal them
+            // from backup and retry once with the same idempotency key, as plain signing does.
+            if (!staleShareRetry && isStaleClientSharesError(error)) {
+                await this.healStaleShares({
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    walletOperation: core.WalletOperation.SIGN_MESSAGE,
+                    mfaToken,
+                    dynamicRequestId,
+                    traceContext,
+                    trigger: 'server 409 stale-shares preflight (sign and broadcast)',
+                    confirmedMismatch: true
+                });
+                this.logger.info('[StaleShareCheck] retrying sign and broadcast after 409 stale-shares preflight', _extends({
+                    key: 'signAndBroadcast',
+                    operation: 'staleShareRetry',
+                    accountAddress,
+                    chainName,
+                    dynamicRequestId,
+                    stage
+                }, this.getTraceContext(traceContext)));
+                return await this.internalSignAndBroadcast(_extends({}, retryParams, {
+                    staleShareRetry: true,
+                    roomIdRetry
+                }));
+            }
+            // A cached room was already claimed by an earlier ceremony. Retry once with the same
+            // idempotency key and no cached rooms, so the server opens fresh ones.
+            if (!roomIdRetry && isRoomIdAlreadyUsedError(error)) {
+                this.logger.info('[RoomCache] retrying sign and broadcast without cached rooms after 409 ROOM_ID_ALREADY_USED', _extends({
+                    key: 'signAndBroadcast',
+                    operation: 'roomIdRetry',
+                    accountAddress,
+                    chainName,
+                    dynamicRequestId,
+                    stage
+                }, this.getTraceContext(traceContext)));
+                return await this.internalSignAndBroadcast(_extends({}, retryParams, {
+                    staleShareRetry,
+                    roomIdRetry: true
+                }));
+            }
+            this.reportSignError({
+                error,
+                accountAddress,
+                chainName,
+                isFormatted: false,
+                dynamicRequestId,
+                traceContext,
+                operation: 'signAndBroadcast',
+                details: {
+                    stage,
+                    attemptCount: messages.length,
+                    roomIdSource,
+                    staleShareRetry,
+                    roomIdRetry
+                }
+            });
+            core.attachRequestIds(error, {
+                traceId: traceContext.traceId,
+                requestId: dynamicRequestId
+            });
+            throw error;
+        }
+    }
+    /**
    * Reports a sign that spent a long time before reaching the network. Emitted
    * once per slow sign with the phase breakdown, so a stall can be attributed
    * without guessing: a shared dependency shows up as many signs reporting a
@@ -5157,11 +5560,83 @@ class DynamicWalletClient {
             dynamicRequestId
         }, this.getTraceContext(traceContext)));
     }
-    async getCachedRoomForSign(wallet, accountAddress, chainName, traceContext) {
+    /**
+   * Takes one already-opened room per message from the local pool, or none: a partial set saves nothing, so the server opens them all instead.
+   *
+   * @param wallet - The wallet signing; its key scheme decides which rooms fit.
+   * @param accountAddress - The wallet's address, for logs.
+   * @param chainName - The wallet's chain, for logs.
+   * @param count - How many rooms are needed: one per message.
+   * @param dynamicRequestId - Id of this request, so the pool's logs join the sign's.
+   * @param traceContext - Trace ids for the same reason.
+   * @returns The room ids, or `undefined` when the pool cannot cover every message.
+   */ async getCachedRoomsForSignAndBroadcast(wallet, accountAddress, chainName, count, dynamicRequestId, traceContext) {
+        const logContext = _extends({
+            dynamicRequestId
+        }, this.getTraceContext(traceContext));
         if (this.featureFlags[core.FEATURE_FLAGS.ENABLE_ROOM_CACHE_FLAG] !== true) {
+            this.logCachedRoomsUnavailable({
+                reason: 'cache_disabled',
+                accountAddress,
+                chainName,
+                count,
+                logContext
+            });
             return undefined;
         }
-        const room = await this.getRoom(RoomTypeEnum.RoomTypeEnum.Threshold, wallet.thresholdSignatureScheme);
+        const rooms = await this.takeRooms({
+            roomType: RoomTypeEnum.RoomTypeEnum.Threshold,
+            thresholdSignatureScheme: wallet.thresholdSignatureScheme,
+            count,
+            logContext
+        });
+        if (rooms.length === 0) {
+            this.logCachedRoomsUnavailable({
+                reason: 'pool_too_small',
+                accountAddress,
+                chainName,
+                count,
+                logContext
+            });
+            return undefined;
+        }
+        const roomIds = rooms.map((room)=>room.roomId);
+        this.logger.info('[DynamicWaasWalletClient] Using cached rooms', _extends({
+            key: 'signAndBroadcast',
+            operation: 'cachedRoomsFound',
+            accountAddress,
+            chainName,
+            walletId: wallet.walletId,
+            roomIds
+        }, logContext));
+        return roomIds;
+    }
+    /**
+   * Logs why no cached rooms were sent, so how often the cache covers a request can be measured.
+   *
+   * @param params.reason - `cache_disabled` or `pool_too_small`.
+   * @param params.accountAddress - The wallet's address.
+   * @param params.chainName - The wallet's chain.
+   * @param params.count - How many rooms were needed.
+   * @param params.logContext - Request and trace ids to attach.
+   */ logCachedRoomsUnavailable({ reason, accountAddress, chainName, count, logContext }) {
+        this.logger.info('[DynamicWaasWalletClient] Cached rooms unavailable; the server opens them', _extends({
+            key: 'signAndBroadcast',
+            operation: 'cachedRoomsUnavailable',
+            reason,
+            accountAddress,
+            chainName,
+            requestedCount: count
+        }, logContext));
+    }
+    async getCachedRoomForSign(wallet, accountAddress, chainName, dynamicRequestId, traceContext) {
+        if (this.featureFlags[core.FEATURE_FLAGS.ENABLE_ROOM_CACHE_FLAG] !== true) {
+            return undefined;
+        }
+        const logContext = _extends({
+            dynamicRequestId
+        }, this.getTraceContext(traceContext));
+        const room = await this.getRoom(RoomTypeEnum.RoomTypeEnum.Threshold, wallet.thresholdSignatureScheme, logContext);
         const roomId = room == null ? void 0 : room.roomId;
         if (roomId) {
             this.logger.info('[DynamicWaasWalletClient] Using cached room', _extends({
@@ -5171,7 +5646,7 @@ class DynamicWalletClient {
                 chainName,
                 walletId: wallet.walletId,
                 roomId
-            }, this.getTraceContext(traceContext)));
+            }, logContext));
         }
         return roomId;
     }
@@ -5238,38 +5713,130 @@ class DynamicWalletClient {
             clearTimeout(warningTimer);
         }
     }
+    /** Verifies the password, loads the wallet and makes sure its client share exists: the start of every sign. */ async prepareWalletForSign({ accountAddress, password, signedSessionId, onSignPhase }) {
+        const startedAt = Date.now();
+        onSignPhase == null ? void 0 : onSignPhase('verifyPassword');
+        await this.verifyPassword({
+            accountAddress,
+            password,
+            signedSessionId
+        });
+        const passwordVerifiedAt = Date.now();
+        onSignPhase == null ? void 0 : onSignPhase('getWallet');
+        const wallet = await this.getWallet({
+            accountAddress,
+            password,
+            walletOperation: core.WalletOperation.SIGN_MESSAGE,
+            signedSessionId
+        });
+        const walletLoadedAt = Date.now();
+        const derivationPath = wallet.derivationPath && wallet.derivationPath != '' ? new Uint32Array(Object.values(JSON.parse(wallet.derivationPath))) : undefined;
+        onSignPhase == null ? void 0 : onSignPhase('ensureClientShare');
+        const clientKeyShares = await this.ensureClientShare(accountAddress);
+        const sharesReadyAt = Date.now();
+        return {
+            wallet,
+            derivationPath,
+            clientKeyShares,
+            timings: {
+                startedAt,
+                passwordVerifiedAt,
+                walletLoadedAt,
+                sharesReadyAt
+            }
+        };
+    }
+    /**
+   * Watches a ceremony for a client-side ERROR_PUBLIC_KEY_MISMATCH, the only place a stale
+   * local share surfaces when a generic server error wins the race and masks it. Schedules a
+   * heal as soon as it settles and returns a reader for the mismatch.
+   */ trackClientSignMismatch(clientSignPromise, healContext) {
+        let mismatch;
+        clientSignPromise.catch((error)=>{
+            if (isPublicKeyMismatchError(error)) {
+                mismatch = error;
+                this.logger.warn('[StaleShareCheck] clientSign rejected with public-key mismatch — scheduling share recovery', _extends({
+                    accountAddress: healContext.accountAddress,
+                    chainName: healContext.chainName,
+                    dynamicRequestId: healContext.dynamicRequestId
+                }, this.getTraceContext(healContext.traceContext)));
+                void this.healStaleShares(_extends({}, healContext, {
+                    walletOperation: core.WalletOperation.SIGN_MESSAGE,
+                    trigger: 'clientSign rejection',
+                    confirmedMismatch: true
+                }));
+            }
+        });
+        return ()=>mismatch;
+    }
+    /**
+   * Heals stale shares after a failed ceremony so the caller's retry succeeds. The ground-truth
+   * check runs whatever the raced error was, because a generic server error often wins the race
+   * while the client-side mismatch settles later. It no-ops when shares are fresh.
+   */ async healAfterSignFailure(_param) {
+        var { signError, clientSignMismatch } = _param, healContext = _object_without_properties_loose(_param, [
+            "signError",
+            "clientSignMismatch"
+        ]);
+        await this.healStaleShares(_extends({}, healContext, {
+            walletOperation: core.WalletOperation.SIGN_MESSAGE,
+            trigger: 'sign failure',
+            confirmedMismatch: isPublicKeyMismatchError(signError) || clientSignMismatch !== undefined
+        }));
+    }
+    /**
+   * Logs a failed sign or sign-and-broadcast with the same fields on both, so failures can be filtered by operation, HTTP status and backend code.
+   *
+   * @param params.error - What failed.
+   * @param params.accountAddress - The wallet's address.
+   * @param params.chainName - The wallet's chain.
+   * @param params.isFormatted - Whether the message was a hash.
+   * @param params.dynamicRequestId - Id of the failed attempt.
+   * @param params.traceContext - Ids shared by every attempt of this operation.
+   * @param params.operation - Which call failed. Defaults to `sign`.
+   * @param params.details - Where and how it failed, as short values (never request or response bodies).
+   */ reportSignError({ error, accountAddress, chainName, isFormatted, dynamicRequestId, traceContext, operation = 'sign', details }) {
+        logError({
+            message: `Error in ${operation}`,
+            error: error,
+            context: _extends({
+                accountAddress,
+                chainName,
+                isFormatted: isFormatted ? 'true' : 'false',
+                dynamicRequestId,
+                operation
+            }, describeErrorForLog(error), details, this.getTraceContext(traceContext))
+        });
+    }
     async internalSign({ accountAddress, message, chainName, password = undefined, isFormatted = false, signedSessionId, mfaToken, elevatedAccessToken, context, approvalQuorum, onError, traceContext, bitcoinConfig, onSignPhase, onSignDetails, staleShareRetry = false, roomIdRetry = false }) {
         const dynamicRequestId = uuid.v4();
         onSignDetails == null ? void 0 : onSignDetails({
             dynamicRequestId
         });
+        // Retries below reuse this, so every attempt of one sign shares a trace id.
+        traceContext = core.withTraceId(traceContext);
+        this.logger.info('[DynamicWaasWalletClient] Sign started', _extends({
+            key: 'sign',
+            operation: 'start',
+            accountAddress,
+            chainName,
+            isFormatted,
+            dynamicRequestId,
+            staleShareRetry,
+            roomIdRetry
+        }, this.getTraceContext(traceContext)));
         try {
             // Pre-flight phase boundaries. Nothing reaches the network until
             // serverSign below, so a stall here is invisible in server logs — these
             // timestamps are what attribute it to a phase.
-            const preflightStartedAt = Date.now();
-            onSignPhase == null ? void 0 : onSignPhase('verifyPassword');
-            await this.verifyPassword({
-                accountAddress,
-                password,
-                signedSessionId
-            });
-            const passwordVerifiedAt = Date.now();
-            onSignPhase == null ? void 0 : onSignPhase('getWallet');
-            const wallet = await this.getWallet({
+            const { wallet, derivationPath, clientKeyShares, timings: { startedAt: preflightStartedAt, passwordVerifiedAt, walletLoadedAt, sharesReadyAt } } = await this.prepareWalletForSign({
                 accountAddress,
                 password,
-                walletOperation: core.WalletOperation.SIGN_MESSAGE,
-                signedSessionId
+                signedSessionId,
+                onSignPhase
             });
-            const walletLoadedAt = Date.now();
-            const derivationPath = wallet.derivationPath && wallet.derivationPath != '' ? new Uint32Array(Object.values(JSON.parse(wallet.derivationPath))) : undefined;
-            // Ensure client key shares exist before hitting the API
-            onSignPhase == null ? void 0 : onSignPhase('ensureClientShare');
-            const clientKeyShares = await this.ensureClientShare(accountAddress);
-            const sharesReadyAt = Date.now();
             onSignPhase == null ? void 0 : onSignPhase('resolveCachedRoom');
-            const cachedRoomId = roomIdRetry ? undefined : await this.getCachedRoomForSign(wallet, accountAddress, chainName, traceContext);
+            const cachedRoomId = roomIdRetry ? undefined : await this.getCachedRoomForSign(wallet, accountAddress, chainName, dynamicRequestId, traceContext);
             const roomResolvedAt = Date.now();
             this.logSlowSignPreflight({
                 accountAddress,
@@ -5355,9 +5922,7 @@ class DynamicWalletClient {
                 operation: 'serverSign'
             }, this.getTraceContext(traceContext)));
             let signature;
-            // Set by the clientSign rejection handler below; read in the catch to
-            // detect a client-side mismatch masked by a generic SSE race winner.
-            let clientSignMismatchError;
+            let getClientSignMismatch = ()=>undefined;
             try {
                 // Race clientSign against SSE errors so that server-side failures
                 // (e.g. policy violations) immediately reject instead of hanging
@@ -5420,28 +5985,15 @@ class DynamicWalletClient {
                 // a stale-local-share failure surfaces, since the server's generic SSE
                 // error wins the race and masks it. Schedule recovery regardless of
                 // which promise wins or when this rejection settles.
-                clientSignPromise.catch((error)=>{
-                    if (isPublicKeyMismatchError(error)) {
-                        clientSignMismatchError = error;
-                        this.logger.warn('[StaleShareCheck] clientSign rejected with public-key mismatch — scheduling share recovery', _extends({
-                            accountAddress,
-                            chainName,
-                            dynamicRequestId
-                        }, this.getTraceContext(traceContext)));
-                        void this.healStaleShares({
-                            accountAddress,
-                            chainName,
-                            password,
-                            signedSessionId,
-                            walletOperation: core.WalletOperation.SIGN_MESSAGE,
-                            mfaToken,
-                            dynamicRequestId,
-                            traceContext,
-                            bitcoinConfig,
-                            trigger: 'clientSign rejection',
-                            confirmedMismatch: true
-                        });
-                    }
+                getClientSignMismatch = this.trackClientSignMismatch(clientSignPromise, {
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    mfaToken,
+                    dynamicRequestId,
+                    traceContext,
+                    bitcoinConfig
                 });
                 signature = await Promise.race([
                     clientSignPromise,
@@ -5455,23 +6007,17 @@ class DynamicWalletClient {
                 if (isStaleClientSharesError(signError) || isRoomIdAlreadyUsedError(signError)) {
                     throw signError;
                 }
-                // Heal before rethrowing so the caller's retry succeeds. Run the
-                // ground-truth check whatever the raced error was: a generic SSE
-                // error frequently wins the race while the client-side mismatch
-                // settles later, so error-string inspection alone is timing-dependent.
-                // The check no-ops when shares are fresh.
-                await this.healStaleShares({
+                await this.healAfterSignFailure({
+                    signError,
+                    clientSignMismatch: getClientSignMismatch(),
                     accountAddress,
                     chainName,
                     password,
                     signedSessionId,
-                    walletOperation: core.WalletOperation.SIGN_MESSAGE,
                     mfaToken,
                     dynamicRequestId,
                     traceContext,
-                    bitcoinConfig,
-                    trigger: 'sign failure',
-                    confirmedMismatch: isPublicKeyMismatchError(signError) || clientSignMismatchError !== undefined
+                    bitcoinConfig
                 });
                 throw signError;
             }
@@ -5482,6 +6028,7 @@ class DynamicWalletClient {
                 roomId,
                 derivationPath,
                 isFormatted,
+                dynamicRequestId,
                 key: 'sign',
                 operation: 'clientSign'
             }, this.getTraceContext(traceContext)));
@@ -5565,15 +6112,21 @@ class DynamicWalletClient {
                     roomIdRetry: true
                 });
             }
-            logError({
-                message: 'Error in sign',
-                error: error,
-                context: _extends({
-                    accountAddress,
-                    chainName,
-                    isFormatted: isFormatted ? 'true' : 'false',
-                    dynamicRequestId
-                }, this.getTraceContext(traceContext))
+            this.reportSignError({
+                error,
+                accountAddress,
+                chainName,
+                isFormatted,
+                dynamicRequestId,
+                traceContext,
+                details: {
+                    staleShareRetry,
+                    roomIdRetry
+                }
+            });
+            core.attachRequestIds(error, {
+                traceId: traceContext == null ? void 0 : traceContext.traceId,
+                requestId: dynamicRequestId
             });
             throw error;
         }
@@ -7138,7 +7691,42 @@ class DynamicWalletClient {
         }
         return new web.BIP340KeygenResult(extractedPubkey, secretShare);
     }
-    async exportKey({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, traceContext }) {
+    /**
+   * Builds the export Intent for a business-account wallet, to be signed with
+   * the session key and sent as `approvalQuorum` on the export call.
+   *
+   * The `exportId` is the key share's keygen id, so it comes out the same here
+   * and on the export call; the Intent built here binds it. Makes no API call
+   * and starts no ceremony.
+   */ async prepareExportIntent({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, businessAccountId, initiatorUserId, completeBy }) {
+        const wallet = await this.getWallet({
+            accountAddress,
+            password,
+            walletOperation: core.WalletOperation.EXPORT_PRIVATE_KEY,
+            signedSessionId
+        });
+        const mpcSigner = getMPCSigner({
+            chainName,
+            baseRelayUrl: this.baseMPCRelayApiUrl,
+            bitcoinConfig,
+            variant: wallet.variant
+        });
+        const reconstructedKeyShare = await this.getReconstructedKeyShare(accountAddress, mpcSigner);
+        const exportId = await this.getExportId({
+            chainName,
+            clientKeyShare: reconstructedKeyShare,
+            bitcoinConfig,
+            accountAddress: wallet.accountAddress
+        });
+        return core.createExportIntent({
+            accountAddress,
+            businessAccountId,
+            completeBy,
+            exportId,
+            initiatorUserId
+        });
+    }
+    async exportKey({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, approvalQuorum, proposalId, traceContext }) {
         // Public entry point delegates to the private implementation. Keeping the
         // `staleShareRetry` flag off the public signature mirrors sign/refresh/
         // reshare and ensures the transparent 409 retry can't be suppressed by
@@ -7151,10 +7739,12 @@ class DynamicWalletClient {
             signedSessionId,
             mfaToken,
             elevatedAccessToken,
+            approvalQuorum,
+            proposalId,
             traceContext
         });
     }
-    async internalExportKey({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, traceContext, staleShareRetry = false }) {
+    async internalExportKey({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, approvalQuorum, proposalId, traceContext, staleShareRetry = false }) {
         const dynamicRequestId = uuid.v4();
         try {
             const wallet = await this.getWallet({
@@ -7181,7 +7771,10 @@ class DynamicWalletClient {
             // transport has no such stream, so a post-init denial surfaces as an
             // MPC relay timeout there.
             const sseErrorGate = core.createRejectablePromise();
-            const useHttpTransport = this.featureFlags[core.FEATURE_FLAGS.ENABLE_HTTP_WAAS_TRANSPORT] === true && this.featureFlags[core.FEATURE_FLAGS.ENABLE_HTTP_WAAS_TRANSPORT_EXPORT] === true;
+            // An export that carries approvals stays on SSE: the server answers the
+            // approval round (`consent_required`) on that stream, and the HTTP route
+            // refuses `approvalQuorum` / `proposalId`.
+            const useHttpTransport = this.featureFlags[core.FEATURE_FLAGS.ENABLE_HTTP_WAAS_TRANSPORT] === true && this.featureFlags[core.FEATURE_FLAGS.ENABLE_HTTP_WAAS_TRANSPORT_EXPORT] === true && !approvalQuorum && !proposalId;
             // Fresh key per invocation: the transparent stale-share retry below is a
             // NEW ceremony (new shareSetId), so it must not reuse the failed
             // attempt's key — the dedup would replay that row's terminal error.
@@ -7199,6 +7792,8 @@ class DynamicWalletClient {
             const data = useHttpTransport ? await this.apiClient.requestExportKeyJson(_extends({}, exportParams, {
                 idempotencyKey: idempotencyKey
             })) : await this.apiClient.exportKey(_extends({}, exportParams, {
+                approvalQuorum,
+                proposalId,
                 onError: (error)=>sseErrorGate.reject(error)
             }));
             this.logger.debug('[DynamicWaasWalletClient] Starting export of private key', _extends({
@@ -7267,6 +7862,8 @@ class DynamicWalletClient {
                     signedSessionId,
                     mfaToken,
                     elevatedAccessToken,
+                    approvalQuorum,
+                    proposalId,
                     traceContext,
                     staleShareRetry: true
                 });
@@ -10677,8 +11274,25 @@ class DynamicWalletClient {
         const MPC_SCHEME_CONFIG = core.MPC_CONFIG[thresholdSignatureScheme];
         return roomType === RoomTypeEnum.RoomTypeEnum.Threshold ? MPC_SCHEME_CONFIG.threshold : MPC_SCHEME_CONFIG.numberOfParties;
     }
-    async getRoom(roomType, thresholdSignatureScheme) {
-        var _DynamicWalletClient_rooms_numberOfParties;
+    async getRoom(roomType, thresholdSignatureScheme, logContext) {
+        const [room] = await this.takeRooms({
+            roomType,
+            thresholdSignatureScheme,
+            count: 1,
+            logContext
+        });
+        return room;
+    }
+    /**
+   * Takes `count` cached rooms, or none when the pool holds fewer: a caller that needs every room gains nothing from some of them, and would spend them.
+   *
+   * @param params.roomType - Which kind of room.
+   * @param params.thresholdSignatureScheme - The key scheme; it decides how many parties the room needs.
+   * @param params.count - How many rooms to take.
+   * @param params.logContext - Request and trace ids, so the pool's log joins the operation's.
+   * @returns The rooms taken, or an empty list.
+   */ async takeRooms({ roomType, thresholdSignatureScheme, count, logContext }) {
+        var _rooms_, _DynamicWalletClient_rooms_numberOfParties;
         const numberOfParties = this.getNumberOfParties(roomType, thresholdSignatureScheme);
         const consume = async ()=>{
             // Re-read from localStorage rather than the in-memory static so we see rooms
@@ -10691,29 +11305,34 @@ class DynamicWalletClient {
             const schemeRooms = storedRooms[numberOfParties] || [];
             // Filter out expired rooms and remove the next available room.
             const filteredRooms = schemeRooms.filter((room)=>room.expiresAt > now);
-            const room = filteredRooms.shift();
+            const taken = filteredRooms.length >= count ? filteredRooms.splice(0, count) : [];
             // Use setRooms() rather than replacing DynamicWalletClient.rooms wholesale.
             // setRooms() only mutates the specific numberOfParties key, so rooms for other
             // party counts and any rooms written in-memory by a concurrent createRooms()
             // call that hasn't flushed to storage yet are preserved. Persistence is also
             // routed through the existing persistRooms() chain to keep writes serialized.
             await this.setRooms(numberOfParties, filteredRooms);
-            return room;
+            return taken;
         };
         // Use the Web Locks API for cross-tab mutual exclusion so that two tabs
         // cannot both consume the same cached room. Falls back to a direct call in
         // environments where navigator.locks is unavailable (e.g. Node.js tests).
         const webLocksAvailable = typeof navigator !== 'undefined' && !!navigator.locks;
-        const room = webLocksAvailable ? await navigator.locks.request(`${this.storageKey}-room-cache`, consume) : await consume();
+        const rooms = webLocksAvailable ? await navigator.locks.request(`${this.storageKey}-room-cache`, consume) : await consume();
         var _DynamicWalletClient_rooms_numberOfParties_length;
-        this.logger.info('[DynamicWaasWalletClient] getRoom result', {
+        this.logger.info('[DynamicWaasWalletClient] getRoom result', _extends({
             key: 'roomCache',
             operation: 'getRoom',
             numberOfParties,
-            roomId: room == null ? void 0 : room.roomId,
+            roomId: (_rooms_ = rooms[0]) == null ? void 0 : _rooms_.roomId,
+            requestedCount: count,
+            takenCount: rooms.length
+        }, count > 1 ? {
+            roomIds: rooms.map((room)=>room.roomId)
+        } : {}, logContext, {
             remainingInMemory: (_DynamicWalletClient_rooms_numberOfParties_length = (_DynamicWalletClient_rooms_numberOfParties = DynamicWalletClient.rooms[numberOfParties]) == null ? void 0 : _DynamicWalletClient_rooms_numberOfParties.length) != null ? _DynamicWalletClient_rooms_numberOfParties_length : 0,
             webLocksAvailable
-        });
+        }));
         // If less than or only 1 room left after removing one, trigger async creation for more rooms.
         // The catch prevents an unhandled promise rejection when the API
         // rate-limits this best-effort background call — createRooms already
@@ -10726,7 +11345,7 @@ class DynamicWalletClient {
                 roomCount: ROOM_CACHE_COUNT
             }).catch(()=>{});
         }
-        return room;
+        return rooms;
     }
     getTraceContext(traceContext) {
         const now = Date.now();
@@ -10831,6 +11450,7 @@ class DynamicWalletClient {
             this.startLoggerContext(authToken);
         }
         this.forwardMPCEnabled = this.featureFlags && this.featureFlags[core.FEATURE_FLAGS.ENABLE_FORWARD_MPC_CLIENT_FLAG] === true;
+        this.enclaveSnapshot = this.forwardMPCEnabled ? trackForwardMpcEnclave(this.apiClient.forwardMPCClient) : undefined;
         if (this.forwardMPCEnabled) {
             this.connectForwardMPC();
         }
@@ -11002,6 +11622,7 @@ exports.resolveLogLevel = resolveLogLevel;
 exports.retryPromise = retryPromise;
 exports.shouldReshareToSameBackups = shouldReshareToSameBackups;
 exports.timeoutPromise = timeoutPromise;
+exports.trackForwardMpcEnclave = trackForwardMpcEnclave;
 Object.keys(core).forEach(function (k) {
     if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
         enumerable: true,