@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.15.0-bopen.1

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");
@@ -16,9 +17,16 @@ const WERR_errors_1 = require("../sdk/WERR_errors");
 const utilityHelpers_1 = require("../utility/utilityHelpers");
 const WalletError_1 = require("../sdk/WalletError");
 const utilityHelpers_noBuffer_1 = require("../utility/utilityHelpers.noBuffer");
+const classifyOutputUtxo_1 = require("../services/classifyOutputUtxo");
+const noSendExpiryLifecycle_1 = require("./methods/noSendExpiryLifecycle");
+const validateSyncProof_1 = require("./methods/validateSyncProof");
 const actionBatch_1 = require("./methods/actionBatch");
 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;
@@ -26,12 +34,16 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
     commissionSatoshis;
     commissionPubKeyHex;
     maxRecursionDepth;
+    actionBatchMaxReservedOutputs;
+    managedChangePolicy;
     scriptVerifier;
     static defaultOptions() {
         const opts = {
             feeModel: { model: 'sat/kb', value: 100 },
             commissionSatoshis: 0,
-            commissionPubKeyHex: undefined
+            commissionPubKeyHex: undefined,
+            actionBatchMaxReservedOutputs: 256,
+            managedChangePolicy: (0, managedChangePolicy_1.defaultManagedChangePolicy)()
         };
         return opts;
     }
@@ -48,6 +60,12 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         this.commissionPubKeyHex = options.commissionPubKeyHex;
         this.commissionSatoshis = options.commissionSatoshis;
         this.maxRecursionDepth = 12;
+        const maxReservedOutputs = options.actionBatchMaxReservedOutputs ?? 256;
+        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;
+        this.managedChangePolicy = (0, managedChangePolicy_1.validateManagedChangePolicy)(options.managedChangePolicy);
         this.scriptVerifier = options.scriptVerifier;
     }
     /** Mark a planned set of change inputs spent within the caller's transaction. */
@@ -77,13 +95,21 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
     }
     /** Read only the fields needed by the in-memory funding planner. */
     async findAvailableManagedChangeInputCandidates(userId, basketId, excludeSending, trx) {
-        return (await this.findAvailableManagedChangeInputs(userId, basketId, excludeSending, trx))
-            .map(({ outputId, transactionId, satoshis, txid, vout }) => ({
+        const outputs = await this.findAvailableManagedChangeInputs(userId, basketId, excludeSending, trx);
+        // Keep prototype-level/custom provider fallbacks working even when a
+        // minimal older implementation has not exposed the additive batch status
+        // lookup. createAction resolves missing metadata before tier planning.
+        const findStatuses = this.findTransactionStatusesByIds?.bind(this);
+        const statuses = findStatuses == null
+            ? new Map()
+            : await findStatuses(userId, outputs.map(output => output.transactionId), trx);
+        return outputs.map(({ outputId, transactionId, satoshis, txid, vout }) => ({
             outputId,
             transactionId,
             satoshis,
             txid,
-            vout
+            vout,
+            transactionStatus: statuses.get(transactionId)
         }));
     }
     /** Read the current status of a set of source transactions without loading raw transaction bytes. */
@@ -178,7 +204,77 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
         throw new WERR_errors_1.WERR_NOT_IMPLEMENTED();
     }
     async getCapabilities() {
-        return this.supportsActionBatchPersistence() ? (0, actionBatch_1.getActionBatchCapabilities)() : {};
+        return {
+            ...(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');
+        if (!this.supportsNoSendExpiryPersistence()) {
+            throw new WERR_errors_1.WERR_NOT_IMPLEMENTED('BRC-177 atomic lifecycle persistence');
+        }
+        return await (0, noSendExpiry_1.prepareNoSendExpiry)(this, auth, args);
+    }
+    async activateNoSendExpiry(auth, args) {
+        if (auth.isActive !== true)
+            throw new WERR_errors_1.WERR_NOT_ACTIVE('BRC-177 requires the active storage provider');
+        if (!this.supportsNoSendExpiryPersistence()) {
+            throw new WERR_errors_1.WERR_NOT_IMPLEMENTED('BRC-177 atomic lifecycle persistence');
+        }
+        return await (0, noSendExpiry_1.activateNoSendExpiry)(this, auth, args);
+    }
+    async armNoSendExpiry(auth, args) {
+        if (auth.isActive !== true)
+            throw new WERR_errors_1.WERR_NOT_ACTIVE('BRC-177 requires the active storage provider');
+        if (!this.supportsNoSendExpiryPersistence()) {
+            throw new WERR_errors_1.WERR_NOT_IMPLEMENTED('BRC-177 atomic lifecycle persistence');
+        }
+        await (0, noSendExpiry_1.armNoSendExpiry)(this, auth, args);
+    }
+    supportsNoSendExpiryPersistence() {
+        return false;
     }
     supportsActionBatchPersistence() {
         return false;
@@ -198,6 +294,9 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
     async renewActionBatch(auth, batchId) {
         return await (0, actionBatch_1.renewActionBatch)(this, auth, batchId);
     }
+    async resumeActionBatch(auth, args) {
+        return await (0, actionBatch_1.resumeActionBatch)(this, auth, args);
+    }
     async prepareActionBatchCommit(auth, manifest) {
         return await (0, actionBatchBlobs_1.prepareActionBatchCommit)(this, auth, manifest);
     }
@@ -325,14 +424,16 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             }));
         }
         const unAbortableStatus = ['completed', 'failed', 'sending', 'unproven'];
-        if (tx == null || !tx.isOutgoing || unAbortableStatus.includes(tx.status)) {
+        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;
@@ -348,21 +449,19 @@ 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))) {
+                throw new WERR_errors_1.WERR_INVALID_OPERATION('BRC-177 action changed while it was being aborted');
+            }
+        }
         await this.updateTransactionStatus('failed', tx.transactionId, userId, reference, trx);
         if (tx.txid != null && tx.txid !== '') {
             const req = await entities_1.EntityProvenTxReq.fromStorageTxid(this, tx.txid, trx);
@@ -380,47 +479,131 @@ 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);
-            // 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);
-        });
+        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');
+                }
+                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
+                    };
+                }
+                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);
+                const current = (0, utilityHelpers_1.verifyOne)(await this.findTransactions({
+                    partial: { transactionId: r.transactionId },
+                    noRawTx: true
+                }));
+                if (current.noSendExpiryState === 'broadcast' ||
+                    current.noSendExpiryState === 'target-won' ||
+                    current.noSendExpiryState === 'conflicted') {
+                    return { aborted: false };
+                }
+                return { aborted: true };
+            }
+            if (r.__abortAction === 'brc177-reclaim-in-progress')
+                return { aborted: true };
+            if (r.__abortAction === 'brc177-cancelled')
+                return { aborted: true };
+            if (r.__abortAction === 'brc177-target-protected')
+                return { aborted: false };
             // Tone Engel review feedback (PR #122 comment 4444566147 item 3):
             // do not throw on chain-confirmed refusal — surface it via the
             // return value so callers can branch on it. Refusal is positive
@@ -477,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}`;
             }
         }
@@ -568,6 +752,23 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             await this.updateOutput((0, utilityHelpers_1.verifyId)(output.outputId), { spendable: false, spentBy: undefined }, trx);
         }
     }
+    async protectNoSendExpiryReclaimInputOnFailure(tx, trx) {
+        if (tx.txid == null)
+            return false;
+        const target = (0, utilityHelpers_1.verifyOneOrNone)(await this.findTransactions({
+            partial: { userId: tx.userId, noSendExpiryReclaimTxid: tx.txid },
+            noRawTx: true,
+            trx
+        }));
+        if (target == null)
+            return false;
+        // Generic failed-transaction cleanup releases inputs for reuse. A reclaim
+        // is different: the signed target may still be outside the wallet, so its
+        // anchor remains quarantined even when a processor rejects this reclaim.
+        // Keep the race lifecycle intact because a prior submission can still be
+        // proven later; a rejection response is not chain finality.
+        return true;
+    }
     /**
      * For all `status` values besides 'failed', just updates the transaction records status property.
      *
@@ -606,7 +807,9 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             }
             switch (status) {
                 case 'failed':
-                    await this.releaseInputsAllocatedToFailedTransaction(tx, trx);
+                    if (!(await this.protectNoSendExpiryReclaimInputOnFailure(tx, trx))) {
+                        await this.releaseInputsAllocatedToFailedTransaction(tx, trx);
+                    }
                     await this.markFailedTransactionOutputsNotSpendable(tx, trx);
                     break;
                 case 'nosend':
@@ -689,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
@@ -741,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
@@ -754,21 +958,77 @@ 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 output = (0, utilityHelpers_1.verifyOne)(await this.findOutputs({ partial: { userId: auth.userId, txid, vout } }));
-        return await this.updateOutput(output.outputId, { basketId: undefined });
+        const vargs = (0, validationHelpers_1.validateRelinquishOutputArgs)(args);
+        const { txid, vout } = (0, validationHelpers_1.parseWalletOutpoint)(vargs.output);
+        return await this.transaction(async (trx) => {
+            // Keep existing "not found" behavior for a missing output.
+            const output = (0, utilityHelpers_1.verifyOne)(await this.findOutputs({ partial: { userId: auth.userId, txid, vout }, trx }));
+            // Confirm the output actually belongs to the caller-claimed basket before
+            // clearing it. Without this, any caller that names an arbitrary basket it
+            // happens to hold basket-removal permission for could relinquish (and
+            // thereby free for reuse/spend by whichever app claims the output next)
+            // an output belonging to a different basket entirely, by outpoint alone.
+            const basket = (0, utilityHelpers_1.verifyOneOrNone)(await this.findOutputBaskets({ partial: { userId: auth.userId, name: vargs.basket }, trx }));
+            if (basket == null || output.basketId == null || output.basketId !== basket.basketId) {
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER('basket', `the basket currently containing output ${vargs.output}`);
+            }
+            return await this.updateOutput(output.outputId, { basketId: undefined }, trx);
+        });
     }
     async processSyncChunk(args, chunk) {
-        const user = (0, utilityHelpers_1.verifyTruthy)(await this.findUserByIdentityKey(args.identityKey));
-        const ss = new entities_1.EntitySyncState((0, utilityHelpers_1.verifyOne)(await this.findSyncStates({
-            partial: {
-                storageIdentityKey: args.fromStorageIdentityKey,
-                userId: user.userId
+        // Canonicalize before text-key lookup in every sync mode. Direct
+        // backup/conflict sync retains its established trust for new proof rows,
+        // but may replace an existing global proof only after active-chain
+        // validation. RPC validates every proof before reaching this method.
+        const incomingProofs = chunk.provenTxs ?? [];
+        for (const proof of incomingProofs)
+            (0, validateSyncProof_1.canonicalizeSyncProofIdentifiers)(proof);
+        if (incomingProofs.length > 0) {
+            const existingProofs = await this.findProvenTxs({
+                partial: {},
+                txids: [...new Set(incomingProofs.map(proof => proof.txid))]
+            });
+            const existingByTxid = new Map(existingProofs.map(proof => [proof.txid.toLowerCase(), proof]));
+            for (const proof of incomingProofs) {
+                const existing = existingByTxid.get(proof.txid);
+                if (existing == null)
+                    (0, validateSyncProof_1.markSyncProofInsertOnly)(proof);
+                else if (!(0, validateSyncProof_1.sameSyncProof)(existing, proof))
+                    await (0, validateSyncProof_1.validateSyncProof)(this, proof);
             }
-        })));
-        const r = await ss.processSyncChunk(this, args, chunk);
-        return r;
+        }
+        // A sync page may contain hundreds of related entities. Keep their lookups,
+        // inserts, ID remapping, and sync-state checkpoint in one transaction. This
+        // avoids a transaction startup/commit for every record (especially costly
+        // in IndexedDB) and makes the page checkpoint atomic with its data changes.
+        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
+                    },
+                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)) {
+                    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;
+        });
     }
     /**
      * Handles storage changes when a valid MerklePath and mined block header are found for a ProvenTxReq txid.
@@ -783,8 +1043,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...
@@ -796,19 +1059,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';
@@ -828,6 +1092,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.
@@ -874,7 +1166,16 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             for (const output of outputs) {
                 const outputId = (0, utilityHelpers_1.verifyId)(output.outputId);
                 await this.validateOutputScript(output);
-                verdicts.set(outputId, output.lockingScript == null ? undefined : await services.isUtxo(output));
+                if (output.lockingScript == null) {
+                    verdicts.set(outputId, undefined);
+                    continue;
+                }
+                const classification = await (0, classifyOutputUtxo_1.classifyOutputUtxo)(services, output);
+                // Proof recovery must not turn provider absence into a spent verdict.
+                // 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');
             }
         }
         return verdicts;
@@ -920,18 +1221,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;
@@ -941,8 +1238,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;
@@ -1064,20 +1360,14 @@ class StorageProvider extends StorageReaderWriter_1.StorageReaderWriter {
             for (const o of outputs) {
                 if (!o.spendable)
                     continue;
-                const isUtxo = await this.checkOutputIsUtxo(o, services);
+                await this.validateOutputScript(o);
+                const isUtxo = (0, classifyOutputUtxo_1.requireConclusiveUtxo)(await (0, classifyOutputUtxo_1.classifyOutputUtxo)(services, o));
                 if (!isUtxo)
                     invalidSpendableOutputs.push(o);
             }
         }
         return { invalidSpendableOutputs };
     }
-    async checkOutputIsUtxo(o, services) {
-        if (o.lockingScript == null || o.lockingScript.length === 0)
-            return false;
-        const hash = services.hashOutputScript((0, utilityHelpers_noBuffer_1.asString)(o.lockingScript));
-        const r = await services.getUtxoStatus(hash, undefined, `${o.txid ?? ''}.${o.vout ?? ''}`);
-        return r.isUtxo === true;
-    }
     async updateProvenTxReqDynamics(id, update, trx) {
         const partial = {};
         if (update.updated_at != null)