@bsv/wallet-toolbox 2.13.0 → 2.13.2

package/out/src/storage/StorageProvider.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageProvider = void 0;
 exports.validateStorageFeeModel = validateStorageFeeModel;
+const validationHelpers_1 = require("@bsv/sdk/wallet/validationHelpers");
 const sdk_1 = require("@bsv/sdk");
 const storageProviderHelpers_1 = require("./storageProviderHelpers");
 const getBeefForTransaction_1 = require("./methods/getBeefForTransaction");
@@ -24,6 +25,8 @@ const actionBatchBlobs_1 = require("./methods/actionBatchBlobs");
 const availableManagedChange_1 = require("./methods/availableManagedChange");
 const managedChangePolicy_1 = require("./methods/managedChangePolicy");
 const noSendExpiry_1 = require("./methods/noSendExpiry");
+const MAX_AUTH_PROOF_REQUEST_FALLBACK_ROWS = 10_000;
+const MAX_AUTH_PROOF_REQUEST_TXIDS = 1_000;
 class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
     isDirty = false;
     _services;
@@ -58,8 +61,7 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         this.commissionSatoshis = options.commissionSatoshis;
         this.maxRecursionDepth = 12;
         const maxReservedOutputs = options.actionBatchMaxReservedOutputs ?? 256;
-        if (maxReservedOutputs !== -1 &&
-            (!Number.isSafeInteger(maxReservedOutputs) || maxReservedOutputs < 1)) {
+        if (maxReservedOutputs !== -1 && (!Number.isSafeInteger(maxReservedOutputs) || maxReservedOutputs < 1)) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('actionBatchMaxReservedOutputs', 'a positive safe integer or -1 for unlimited');
         }
         this.actionBatchMaxReservedOutputs = maxReservedOutputs;
@@ -203,14 +205,50 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
     }
     async getCapabilities() {
         return {
-            ...(this.supportsNoSendExpiryPersistence()
-                ? { brc177NoSendExpiry: { version: 1 } }
-                : {}),
+            ...(this.supportsNoSendExpiryPersistence() ? { brc177NoSendExpiry: { version: 1 } } : {}),
             ...(this.supportsActionBatchPersistence()
                 ? (0, actionBatch_1.getActionBatchCapabilities)(this.actionBatchMaxReservedOutputs, true)
                 : {})
         };
     }
+    /**
+     * Restrict remotely requested proof work to transactions tracked by the
+     * authenticated wallet. ProvenTxReq rows are globally deduplicated, so their
+     * own schema has no userId column and must be authorized through transactions.
+     */
+    async findProvenTxReqsAuth(auth, args) {
+        const userId = (0, utilityHelpers_1.verifyId)(auth.userId);
+        let requestedTxids;
+        if (args.txids?.length) {
+            if (args.txids.length > MAX_AUTH_PROOF_REQUEST_TXIDS) {
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.txids', `at most ${MAX_AUTH_PROOF_REQUEST_TXIDS} transaction IDs`);
+            }
+            requestedTxids = [];
+            for (const txid of args.txids) {
+                if ((await this.countTransactions({ partial: { userId, txid }, trx: args.trx })) > 0) {
+                    requestedTxids.push(txid);
+                }
+            }
+        }
+        else {
+            // Built-in providers override this method with a joined/indexed query.
+            // Keep third-party implementations safe even when they only implement
+            // the older reader surface: bound the compatibility ownership scan and
+            // require exact txids for wallets beyond it.
+            const owned = await this.getProvenTxReqsForUser({
+                userId,
+                paged: { limit: MAX_AUTH_PROOF_REQUEST_FALLBACK_ROWS + 1, offset: 0 },
+                trx: args.trx
+            });
+            if (owned.length > MAX_AUTH_PROOF_REQUEST_FALLBACK_ROWS) {
+                throw new WERR_errors_1.WERR_INVALID_OPERATION('Authenticated proof-request scans beyond 10,000 rows require a provider-native scoped query or exact txids');
+            }
+            requestedTxids = owned.map(request => request.txid);
+        }
+        if (requestedTxids.length === 0)
+            return [];
+        return await this.findProvenTxReqs({ ...args, txids: requestedTxids });
+    }
     async prepareNoSendExpiry(auth, args) {
         if (auth.isActive !== true)
             throw new WERR_errors_1.WERR_NOT_ACTIVE('BRC-177 requires the active storage provider');
@@ -386,22 +424,16 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             }));
         }
         const unAbortableStatus = ['completed', 'failed', 'sending', 'unproven'];
-        const brc177TerminalOrRacing = tx?.noSendExpiryState != null && [
-            'broadcast',
-            'reclaiming',
-            'reclaimed',
-            'target-won',
-            'conflicted',
-            'cancelled'
-        ].includes(tx.noSendExpiryState);
+        const brc177TerminalOrRacing = tx?.noSendExpiryState != null &&
+            ['broadcast', 'reclaiming', 'reclaimed', 'target-won', 'conflicted', 'cancelled'].includes(tx.noSendExpiryState);
         if (tx == null || !tx.isOutgoing || (unAbortableStatus.includes(tx.status) && !brc177TerminalOrRacing)) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('reference', 'an inprocess, outgoing action that has not been signed and shared to the network.');
         }
         return { tx, reference };
     }
-    async checkAbortChainProtection(tx, args, trx) {
-        if (tx.txid == null || tx.txid === '' || tx.status !== 'nosend') {
-            return { skipped: false, serviceUnreachable: false };
+    async observeAbortChainProtection(tx) {
+        if (tx.txid == null || tx.txid === '' || tx.status !== 'nosend' || tx.noSendExpiryState != null) {
+            return undefined;
         }
         let serviceUnreachable = false;
         let chainStatus;
@@ -417,23 +449,16 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         catch {
             serviceUnreachable = true;
         }
-        if (chainStatus !== 'mined' && chainStatus !== 'known') {
-            return { skipped: false, serviceUnreachable };
-        }
-        const req = await entities_1.EntityProvenTxReq.fromStorageTxid(this, tx.txid, trx);
-        if (req != null) {
-            req.addHistoryNote({
-                what: 'abortAction-skipped-onchain',
-                reference: args.reference,
-                chainStatus
-            });
-            await req.updateStorageDynamicProperties(this, trx);
-        }
-        return { skipped: true, serviceUnreachable };
+        return {
+            transactionId: tx.transactionId,
+            txid: tx.txid,
+            chainStatus,
+            serviceUnreachable
+        };
     }
     async invalidateAbortedTransaction(tx, userId, reference, originalReference, serviceUnreachable, trx) {
         if (tx.noSendExpiryState === 'preparing' || tx.noSendExpiryState === 'unsigned') {
-            if (!await this.compareAndSetNoSendExpiryState(tx.transactionId, tx.noSendExpiryState, 'cancelled', trx)) {
+            if (!(await this.compareAndSetNoSendExpiryState(tx.transactionId, tx.noSendExpiryState, 'cancelled', trx))) {
                 throw new WERR_errors_1.WERR_INVALID_OPERATION('BRC-177 action changed while it was being aborted');
             }
         }
@@ -454,82 +479,111 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         if (auth.userId == null)
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('auth.userId', 'valid');
         const userId = auth.userId;
-        const r = await this.transaction(async (trx) => {
-            const { tx, reference } = await this.findAbortableTransaction(userId, args, trx);
-            if (tx.noSendExpiryState != null && auth.isActive !== true) {
-                throw new WERR_errors_1.WERR_NOT_ACTIVE('BRC-177 requires the active storage provider');
-            }
-            if (tx.noSendExpiryState === 'signed') {
-                // A released BRC-177 transaction must never be invalidated locally: the
-                // recipient may be broadcasting it at this instant. Make it due and let
-                // the lifecycle's positive chain/UTXO checks arbitrate the race.
-                if (!await this.compareAndSetNoSendExpiryState(tx.transactionId, 'signed', 'revocation-requested', trx)) {
-                    throw new WERR_errors_1.WERR_INVALID_OPERATION('BRC-177 action changed while early revocation was requested');
+        let r;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            // IndexedDB write transactions can auto-commit while awaiting non-database
+            // promises. Observe the chain before opening the write transaction, then
+            // bind the observation to the exact row and txid re-read below.
+            const preflight = await this.findAbortableTransaction(userId, args);
+            const chainObservation = await this.observeAbortChainProtection(preflight.tx);
+            r = await this.transaction(async (trx) => {
+                const { tx, reference } = await this.findAbortableTransaction(userId, args, trx);
+                if (tx.noSendExpiryState != null && auth.isActive !== true) {
+                    throw new WERR_errors_1.WERR_NOT_ACTIVE('BRC-177 requires the active storage provider');
                 }
-                const req = tx.txid == null ? undefined : await entities_1.EntityProvenTxReq.fromStorageTxid(this, tx.txid, trx);
-                if (req != null) {
-                    req.addHistoryNote({ what: 'brc177-early-abort-reclaim-requested', reference: args.reference });
-                    await req.updateStorageDynamicProperties(this, trx);
+                if (tx.noSendExpiryState === 'signed') {
+                    // A released BRC-177 transaction must never be invalidated locally: the
+                    // recipient may be broadcasting it at this instant. Make it due and let
+                    // the lifecycle's positive chain/UTXO checks arbitrate the race.
+                    if (!(await this.compareAndSetNoSendExpiryState(tx.transactionId, 'signed', 'revocation-requested', trx))) {
+                        throw new WERR_errors_1.WERR_INVALID_OPERATION('BRC-177 action changed while early revocation was requested');
+                    }
+                    const req = tx.txid == null ? undefined : await entities_1.EntityProvenTxReq.fromStorageTxid(this, tx.txid, trx);
+                    if (req != null) {
+                        req.addHistoryNote({ what: 'brc177-early-abort-reclaim-requested', reference: args.reference });
+                        await req.updateStorageDynamicProperties(this, trx);
+                    }
+                    return {
+                        __abortAction: 'brc177-reclaim-requested',
+                        transactionId: tx.transactionId
+                    };
                 }
-                return {
-                    __abortAction: 'brc177-reclaim-requested',
-                    transactionId: tx.transactionId
-                };
-            }
-            if (tx.noSendExpiryState === 'revocation-requested') {
-                return {
-                    __abortAction: 'brc177-reclaim-requested',
-                    transactionId: tx.transactionId
-                };
-            }
-            if (tx.noSendExpiryState === 'reclaiming' || tx.noSendExpiryState === 'reclaimed') {
-                return { __abortAction: 'brc177-reclaim-in-progress' };
-            }
-            if (tx.noSendExpiryState === 'cancelled') {
-                return { __abortAction: 'brc177-cancelled' };
-            }
-            if (tx.noSendExpiryState === 'broadcast' || tx.noSendExpiryState === 'target-won' ||
-                tx.noSendExpiryState === 'conflicted') {
-                return { __abortAction: 'brc177-target-protected' };
-            }
-            // Chain-status protection for signed nosend txs.
-            //
-            // Background: a nosend tx (created via createAction({noSend:true}))
-            // can be externally broadcast by the caller and reach 'mined' or
-            // mempool-'known' status before any internalizeAction or Monitor
-            // cycle has retired its 'nosend' status in storage. If abortAction
-            // is invoked on it in that window, the destructive transitions
-            // below (transactions.status='failed' + proven_tx_reqs.status='invalid')
-            // orphan every output the tx produced — including auto-fund change
-            // outputs the wallet itself emitted — because listOutputs filters
-            // them out of the spendable set on parent-tx 'failed' status.
-            //
-            // Protection: if the tx has a txid AND status is 'nosend', ask
-            // the network whether it already knows about the tx before
-            // invalidating. getStatusForTxids returns 'mined' | 'known' |
-            // 'unknown' per StatusForTxidResult (WalletServices.interfaces.ts).
-            // Refuse the abort for 'mined' OR 'known' — a tx that's broadcast
-            // and propagating in mempool returns 'known' (depth===0) and
-            // protecting it avoids orphaning during the propagation window.
-            //
-            // Service-unreachable handling: proceed with abort. Refusal is
-            // reserved for positive on-chain confirmation. When the network
-            // confirmation pathway is itself unavailable (services throw or
-            // gracefully return r.status !== 'success'), confirmation is not
-            // possible — and per the BRC-100 contract callers retain the
-            // ability to abort offline. The fallback writes a forensic
-            // history note ('abortAction-offline-fallback') so an operator
-            // can grep for aborts that proceeded under uncertainty. This
-            // hole can never be 100% closed against externally-broadcast
-            // chain-confirmed txs while offline; the audit trail makes it
-            // recoverable.
-            const protection = await this.checkAbortChainProtection(tx, args, trx);
-            if (protection.skipped) {
-                // Commit the audit note before translating this sentinel to aborted:false.
-                return { __abortAction: 'skipped-onchain' };
-            }
-            return await this.invalidateAbortedTransaction(tx, userId, reference, args.reference, protection.serviceUnreachable, trx);
-        });
+                if (tx.noSendExpiryState === 'revocation-requested') {
+                    return {
+                        __abortAction: 'brc177-reclaim-requested',
+                        transactionId: tx.transactionId
+                    };
+                }
+                if (tx.noSendExpiryState === 'reclaiming' || tx.noSendExpiryState === 'reclaimed') {
+                    return { __abortAction: 'brc177-reclaim-in-progress' };
+                }
+                if (tx.noSendExpiryState === 'cancelled') {
+                    return { __abortAction: 'brc177-cancelled' };
+                }
+                if (tx.noSendExpiryState === 'broadcast' ||
+                    tx.noSendExpiryState === 'target-won' ||
+                    tx.noSendExpiryState === 'conflicted') {
+                    return { __abortAction: 'brc177-target-protected' };
+                }
+                // Chain-status protection for signed nosend txs.
+                //
+                // Background: a nosend tx (created via createAction({noSend:true}))
+                // can be externally broadcast by the caller and reach 'mined' or
+                // mempool-'known' status before any internalizeAction or Monitor
+                // cycle has retired its 'nosend' status in storage. If abortAction
+                // is invoked on it in that window, the destructive transitions
+                // below (transactions.status='failed' + proven_tx_reqs.status='invalid')
+                // orphan every output the tx produced — including auto-fund change
+                // outputs the wallet itself emitted — because listOutputs filters
+                // them out of the spendable set on parent-tx 'failed' status.
+                //
+                // Protection: if the tx has a txid AND status is 'nosend', ask
+                // the network whether it already knows about the tx before
+                // invalidating. getStatusForTxids returns 'mined' | 'known' |
+                // 'unknown' per StatusForTxidResult (WalletServices.interfaces.ts).
+                // Refuse the abort for 'mined' OR 'known' — a tx that's broadcast
+                // and propagating in mempool returns 'known' (depth===0) and
+                // protecting it avoids orphaning during the propagation window.
+                //
+                // Service-unreachable handling: proceed with abort. Refusal is
+                // reserved for positive on-chain confirmation. When the network
+                // confirmation pathway is itself unavailable (services throw or
+                // gracefully return r.status !== 'success'), confirmation is not
+                // possible — and per the BRC-100 contract callers retain the
+                // ability to abort offline. The fallback writes a forensic
+                // history note ('abortAction-offline-fallback') so an operator
+                // can grep for aborts that proceeded under uncertainty. This
+                // hole can never be 100% closed against externally-broadcast
+                // chain-confirmed txs while offline; the audit trail makes it
+                // recoverable.
+                if (tx.txid != null && tx.txid !== '' && tx.status === 'nosend' && tx.noSendExpiryState == null) {
+                    if (chainObservation == null ||
+                        chainObservation.transactionId !== tx.transactionId ||
+                        chainObservation.txid !== tx.txid) {
+                        return { __abortAction: 'retry-chain-check' };
+                    }
+                    if (chainObservation.chainStatus === 'mined' || chainObservation.chainStatus === 'known') {
+                        const req = await entities_1.EntityProvenTxReq.fromStorageTxid(this, tx.txid, trx);
+                        if (req != null) {
+                            req.addHistoryNote({
+                                what: 'abortAction-skipped-onchain',
+                                reference: args.reference,
+                                chainStatus: chainObservation.chainStatus
+                            });
+                            await req.updateStorageDynamicProperties(this, trx);
+                        }
+                        // Commit the audit note before translating this sentinel to aborted:false.
+                        return { __abortAction: 'skipped-onchain' };
+                    }
+                }
+                return await this.invalidateAbortedTransaction(tx, userId, reference, args.reference, chainObservation?.serviceUnreachable ?? false, trx);
+            });
+            if (!('__abortAction' in r) || r.__abortAction !== 'retry-chain-check')
+                break;
+        }
+        if (r == null || ('__abortAction' in r && r.__abortAction === 'retry-chain-check')) {
+            throw new WERR_errors_1.WERR_INVALID_OPERATION('Action changed while its chain status was being checked; retry abortAction');
+        }
         if ('__abortAction' in r) {
             if (r.__abortAction === 'brc177-reclaim-requested') {
                 await (0, noSendExpiryLifecycle_1.processNoSendExpiryLifecycle)(this).catch(() => undefined);
@@ -537,7 +591,8 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
                     partial: { transactionId: r.transactionId },
                     noRawTx: true
                 }));
-                if (current.noSendExpiryState === 'broadcast' || current.noSendExpiryState === 'target-won' ||
+                if (current.noSendExpiryState === 'broadcast' ||
+                    current.noSendExpiryState === 'target-won' ||
                     current.noSendExpiryState === 'conflicted') {
                     return { aborted: false };
                 }
@@ -605,6 +660,7 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             }
             catch (error_) {
                 const e = WalletError_1.WalletError.fromUnknown(error_);
+                d.status = 'error';
                 d.error = `${e.name}: ${e.message}`;
             }
         }
@@ -836,7 +892,7 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         if (chainTracker != null) {
             const root = mp.computeRoot();
             const isValid = await chainTracker.isValidRootForHeight(root, proven.height);
-            if (!isValid) {
+            if (isValid !== true) {
                 if (skipInvalidProofs !== true)
                     throw new WERR_errors_1.WERR_INVALID_MERKLE_ROOT(proven.blockHash, proven.height, root, txid);
                 // Proof is currently invalid — recurse deeper via rawTx path
@@ -888,9 +944,10 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         return (0, utilityHelpers_1.verifyOneOrNone)(await this.findMonitorEvents({ partial: { id }, trx }));
     }
     async relinquishCertificate(auth, args) {
-        const vargs = sdk_1.Validation.validateRelinquishCertificateArgs(args);
+        const vargs = (0, validationHelpers_1.validateRelinquishCertificateArgs)(args);
         const cert = (0, utilityHelpers_1.verifyOne)(await this.findCertificates({
             partial: {
+                userId: auth.userId,
                 certifier: vargs.certifier,
                 serialNumber: vargs.serialNumber,
                 type: vargs.type
@@ -901,8 +958,8 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         });
     }
     async relinquishOutput(auth, args) {
-        const vargs = sdk_1.Validation.validateRelinquishOutputArgs(args);
-        const { txid, vout } = sdk_1.Validation.parseWalletOutpoint(vargs.output);
+        const vargs = (0, validationHelpers_1.validateRelinquishOutputArgs)(args);
+        const { txid, vout } = (0, validationHelpers_1.parseWalletOutpoint)(vargs.output);
         const output = (0, utilityHelpers_1.verifyOne)(await this.findOutputs({ partial: { userId: auth.userId, txid, vout } }));
         return await this.updateOutput(output.outputId, { basketId: undefined });
     }
@@ -935,28 +992,30 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         return await this.transaction(async (trx) => {
             const user = (0, utilityHelpers_1.verifyTruthy)((0, utilityHelpers_1.verifyOneOrNone)(await this.findUsers({ partial: { identityKey: args.identityKey }, trx })));
             const ss = new entities_1.EntitySyncState((0, utilityHelpers_1.verifyOne)(await this.findSyncStates({
-                partial: args.syncStateId == null ? {
-                    storageIdentityKey: args.fromStorageIdentityKey,
-                    userId: user.userId
-                } : {
-                    syncStateId: args.syncStateId,
-                    storageIdentityKey: args.fromStorageIdentityKey,
-                    userId: user.userId
-                },
+                partial: args.syncStateId == null
+                    ? {
+                        storageIdentityKey: args.fromStorageIdentityKey,
+                        userId: user.userId
+                    }
+                    : {
+                        syncStateId: args.syncStateId,
+                        storageIdentityKey: args.fromStorageIdentityKey,
+                        userId: user.userId
+                    },
                 trx
             })));
             if (args.requireMatchingCheckpoint === true) {
                 const checkpoint = ss.makeSyncCheckpoint();
                 const sameSince = (checkpoint.since == null ? undefined : new Date(checkpoint.since).getTime()) ===
                     (args.since == null ? undefined : new Date(args.since).getTime());
-                if (!sameSince || checkpoint.offsets.length !== args.offsets.length || checkpoint.offsets.some((entry, index) => entry.name !== args.offsets[index]?.name || entry.offset !== args.offsets[index]?.offset)) {
+                if (!sameSince ||
+                    checkpoint.offsets.length !== args.offsets.length ||
+                    checkpoint.offsets.some((entry, index) => entry.name !== args.offsets[index]?.name || entry.offset !== args.offsets[index]?.offset)) {
                     throw new WERR_errors_1.WERR_INVALID_OPERATION('Wallet sync checkpoint changed; resume from its durable state before retrying');
                 }
             }
             const result = await ss.processSyncChunk(this, args, chunk, trx);
-            return args.includeNextCheckpoint === true
-                ? { ...result, nextCheckpoint: ss.makeSyncCheckpoint() }
-                : result;
+            return args.includeNextCheckpoint === true ? { ...result, nextCheckpoint: ss.makeSyncCheckpoint() } : result;
         });
     }
     /**
@@ -972,8 +1031,11 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
      *
      * Alterations of "typically" to handle:
      */
-    async updateProvenTxReqWithNewProvenTx(args) {
+    async updateProvenTxReqWithNewProvenTx(args, validatedCandidate) {
         const req = await entities_1.EntityProvenTxReq.fromStorageId(this, args.provenTxReqId);
+        if (req.txid.toLowerCase() !== args.txid.toLowerCase()) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.txid', 'the transaction id of the selected proof request');
+        }
         let proven;
         if (req.provenTxId != null && req.provenTxId > 0) {
             // Someone beat us to it, grab what we need for results...
@@ -985,19 +1047,20 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             }
         }
         else {
+            const candidate = validatedCandidate ?? {
+                created_at: new Date(),
+                updated_at: new Date(),
+                provenTxId: 0,
+                txid: args.txid,
+                height: args.height,
+                index: args.index,
+                merklePath: args.merklePath,
+                rawTx: req.rawTx,
+                blockHash: args.blockHash,
+                merkleRoot: args.merkleRoot
+            };
             proven = await this.transaction(async (trx) => {
-                const { proven: api } = await this.findOrInsertProvenTx({
-                    created_at: new Date(),
-                    updated_at: new Date(),
-                    provenTxId: 0,
-                    txid: args.txid,
-                    height: args.height,
-                    index: args.index,
-                    merklePath: args.merklePath,
-                    rawTx: req.rawTx,
-                    blockHash: args.blockHash,
-                    merkleRoot: args.merkleRoot
-                }, trx);
+                const { proven: api } = await this.findOrInsertProvenTx(candidate, trx);
                 const found = new entities_1.EntityProvenTx(api);
                 if (req.status !== 'completed' || req.provenTxId !== found.provenTxId) {
                     req.status = 'completed';
@@ -1017,6 +1080,34 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         };
         return r;
     }
+    /** Authorize and validate remote proof completion before mutating shared proof state. */
+    async updateProvenTxReqWithNewProvenTxAuth(auth, args) {
+        const userId = (0, utilityHelpers_1.verifyId)(auth.userId);
+        const req = await entities_1.EntityProvenTxReq.fromStorageId(this, args.provenTxReqId);
+        if (req.txid.toLowerCase() !== args.txid.toLowerCase()) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.txid', 'the transaction id of the selected proof request');
+        }
+        const ownedTransactions = await this.countTransactions({
+            partial: { userId, txid: req.txid }
+        });
+        if (ownedTransactions === 0) {
+            throw new WERR_errors_1.WERR_UNAUTHORIZED('The proof request does not belong to the authenticated wallet.');
+        }
+        const candidate = {
+            created_at: new Date(),
+            updated_at: new Date(),
+            provenTxId: 0,
+            txid: args.txid,
+            height: args.height,
+            index: args.index,
+            merklePath: args.merklePath,
+            rawTx: req.rawTx,
+            blockHash: args.blockHash,
+            merkleRoot: args.merkleRoot
+        };
+        await (0, validateSyncProof_1.validateSyncProof)(this, candidate);
+        return await this.updateProvenTxReqWithNewProvenTx(args, candidate);
+    }
     /**
      * Reconcile completed proof requests whose transaction fan-out previously
      * failed or whose durable notification state drifted.
@@ -1072,9 +1163,7 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
                 // Leave the output's current state unchanged when no UTXO service can
                 // answer conclusively; the validated proof still repairs transaction
                 // and consumed-input state.
-                verdicts.set(outputId, classification.verdict === 'unknown'
-                    ? undefined
-                    : classification.verdict === 'unspent');
+                verdicts.set(outputId, classification.verdict === 'unknown' ? undefined : classification.verdict === 'unspent');
             }
         }
         return verdicts;
@@ -1120,18 +1209,14 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             }
             const isUtxo = outputVerdicts.get(outputId);
             if (isUtxo == null) {
-                log +=
-                    ' '.repeat(indent + 2) +
-                        `output ${output.outputId} does not have a valid locking script\n`;
+                log += ' '.repeat(indent + 2) + `output ${output.outputId} does not have a valid locking script\n`;
                 continue;
             }
             if (isUtxo === output.spendable) {
                 log += ' '.repeat(indent + 2) + `output ${output.outputId} unchanged\n`;
                 continue;
             }
-            log +=
-                ' '.repeat(indent + 2) +
-                    `output ${output.outputId} set to ${isUtxo ? 'spendable' : 'spent'}\n`;
+            log += ' '.repeat(indent + 2) + `output ${output.outputId} set to ${isUtxo ? 'spendable' : 'spent'}\n`;
             await this.updateOutput(outputId, { spendable: isUtxo }, trx);
         }
         return log;
@@ -1141,8 +1226,7 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             throw new WERR_errors_1.WERR_INTERNAL(`Transaction ${tx.transactionId} changed while preparing proof recovery.`);
         }
         await this.updateTransaction(tx.transactionId, { status: 'unproven' }, trx);
-        let log = ' '.repeat(indent) +
-            `transaction ${tx.transactionId} status is now 'unproven'\n`;
+        let log = ' '.repeat(indent) + `transaction ${tx.transactionId} status is now 'unproven'\n`;
         log += await this.restoreProofRecoveryInputs(tx, bsvtx, indent, trx);
         log += await this.restoreProofRecoveryOutputs(tx, outputVerdicts, indent, trx);
         return log;