@bsv/wallet-toolbox 2.10.4 → 2.11.0

package/out/src/storage/methods/createAction.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setDisableDoubleSpendCheckForTest = setDisableDoubleSpendCheckForTest;
 exports.createAction = createAction;
+exports.validateRequiredOutputs = validateRequiredOutputs;
+exports.validateRequiredInputs = validateRequiredInputs;
 const sdk_1 = require("@bsv/sdk");
 const generateChange_1 = require("./generateChange");
 const StorageProvider_1 = require("../StorageProvider");
@@ -50,6 +52,9 @@ async function createActionCore(storage, auth, vargs, parent) {
     // stampLog(vargs, `start storage createTransactionSdk`)
     if (vargs.isTestWerrReviewActions)
         (0, Wallet_1.throwDummyReviewActions)();
+    if (vargs.brc177 != null && auth.isActive !== true) {
+        throw new WERR_errors_1.WERR_NOT_ACTIVE('BRC-177 requires the active storage provider');
+    }
     if (!vargs.isNewTx) 
     // The purpose of this function is to create the initial storage records associated
     // with a new transaction. It's an error if we have no new inputs or outputs...
@@ -100,12 +105,13 @@ async function createActionCore(storage, auth, vargs, parent) {
     const feeModel = (0, StorageProvider_1.validateStorageFeeModel)(storage.feeModel);
     logger?.log(`validated fee model ${JSON.stringify(feeModel)}`);
     const initialFundingPlan = await prepareFundingPlanWithLiquidityPolicy(storage, [userId, vargs, xinputs, xoutputs, changeBasket, noSendChangeIn, feeModel], parent);
+    validateBrc177FundingPlan(vargs, initialFundingPlan);
     logger?.log(`planned funding from ${initialFundingPlan.availableChangeCount} change inputs`);
     // The selected source txids are known before the write transaction begins.
     // Start their one batched proof read now so PXC/network wait and BEEF
     // assembly overlap the independent transaction-record/funding/output writes.
     // A funding-claim retry is handled below by fetching only any residual roots.
-    const allocatedBeefPrefetch = startAllocatedChangeBeefPrefetch(storage, vargs, initialFundingPlan.selected, beef, parent);
+    const allocatedBeefPrefetch = startAllocatedChangeBeefPrefetch(storage, userId, vargs, initialFundingPlan.selected, beef, parent);
     const storageBeefBytes = storageBeef.toBinary();
     let newTx;
     let newTxCommitted = false;
@@ -138,7 +144,11 @@ async function createActionCore(storage, auth, vargs, parent) {
                 ctx.xoutputs[adjustment.fixedOutputIndex].satoshis = adjustment.satoshis;
                 logger?.log('adjusted change outputs to max possible');
             }
-            const satoshis = funded.changeOutputs.reduce((sum, output) => sum + output.satoshis, 0) -
+            const fixedManagedChangeSatoshis = ctx.xoutputs
+                .filter(output => output.purpose === 'change')
+                .reduce((sum, output) => sum + output.satoshis, 0);
+            const satoshis = fixedManagedChangeSatoshis +
+                funded.changeOutputs.reduce((sum, output) => sum + output.satoshis, 0) -
                 funded.allocatedChange.reduce((sum, output) => sum + output.satoshis, 0);
             if (satoshis !== initialSatoshis) {
                 await storage.updateTransaction(newTx.transactionId, { satoshis }, trx);
@@ -158,7 +168,7 @@ async function createActionCore(storage, auth, vargs, parent) {
         const committedTx = (0, utilityHelpers_1.verifyTruthy)(newTx);
         const { allocatedChange, derivationPrefix, outputs, changeVouts, ctx } = persisted;
         logger?.log('created new output records');
-        const inputBeef = await mergeAllocatedChangeBeefs(storage, vargs, allocatedChange, beef, allocatedBeefPrefetch, parent);
+        const preparedInputBeef = await mergeAllocatedChangeBeefs(storage, userId, vargs, allocatedChange, beef, allocatedBeefPrefetch, parent);
         logger?.log('merged allocated change beefs');
         const inputs = await traceStorageStep(storage, 'wallet.storage.create_action.assemble_inputs', parent, {
             'action.fixed_input_count': ctx.xinputs.length,
@@ -177,9 +187,13 @@ async function createActionCore(storage, auth, vargs, parent) {
             inputs,
             outputs,
             derivationPrefix,
-            inputBeef,
+            inputBeef: preparedInputBeef.inputBeef,
             noSendChangeOutputVouts: vargs.isNoSend ? changeVouts : undefined
         };
+        // This is intentionally the last foreground operation. The coordinator
+        // starts on a timer, so the createAction promise and HTTP response can
+        // resolve before any COOK verification or persistence begins.
+        enqueuePreparedBeefs(storage, preparedInputBeef.preparations);
         logger?.groupEnd();
         return r;
     }
@@ -379,6 +393,49 @@ async function persistNewOutput(storage, o, tags, txTags, txBaskets, trx) {
     }
     return describeNewOutput(o, tags, txBaskets);
 }
+async function createRequiredOutput(storage, userId, xo, ctx, txBaskets, trx) {
+    const o = makeDefaultOutput(userId, ctx.transactionId, xo.satoshis, xo.vout);
+    if (xo.purpose === 'service-charge') {
+        const lockingScript = (0, utilityHelpers_noBuffer_1.asArray)(xo.lockingScript);
+        const now = new Date();
+        await storage.insertCommission({
+            userId,
+            transactionId: ctx.transactionId,
+            lockingScript,
+            satoshis: xo.satoshis,
+            isRedeemed: false,
+            keyOffset: (0, utilityHelpers_1.verifyTruthy)(xo.keyOffset),
+            created_at: now,
+            updated_at: now,
+            commissionId: 0
+        }, trx);
+        o.lockingScript = lockingScript;
+        o.providedBy = 'storage';
+        o.purpose = 'storage-commission';
+        o.type = 'custom';
+        o.spendable = false;
+        return { o, tags: [] };
+    }
+    if (xo.purpose === 'change') {
+        o.basketId = ctx.changeBasket.basketId;
+        o.change = true;
+        o.derivationPrefix = (0, utilityHelpers_1.verifyTruthy)(ctx.derivationPrefix);
+        o.derivationSuffix = (0, utilityHelpers_1.verifyTruthy)(xo.derivationSuffix);
+        o.providedBy = 'storage';
+        o.purpose = 'change';
+        o.type = 'P2PKH';
+        o.spendable = true;
+        return { o, tags: [] };
+    }
+    o.lockingScript = (0, utilityHelpers_noBuffer_1.asArray)(xo.lockingScript);
+    o.basketId = xo.basket ? txBaskets[xo.basket].basketId : undefined;
+    o.customInstructions = xo.customInstructions;
+    o.outputDescription = xo.outputDescription;
+    o.providedBy = xo.providedBy;
+    o.purpose = xo.purpose || '';
+    o.type = 'custom';
+    return { o, tags: xo.tags };
+}
 async function createNewOutputs(storage, userId, vargs, ctx, changeOutputs, trx) {
     const txBaskets = {};
     const basketNames = [...new Set(ctx.xoutputs.map(x => x.basket).filter((v) => !!v))];
@@ -388,39 +445,7 @@ async function createNewOutputs(storage, userId, vargs, ctx, changeOutputs, trx)
     Object.assign(txTags, await storage.findOrInsertOutputTagsBulk(userId, tagNames, trx));
     const newOutputs = [];
     for (const xo of ctx.xoutputs) {
-        const lockingScript = (0, utilityHelpers_noBuffer_1.asArray)(xo.lockingScript);
-        if (xo.purpose === 'service-charge') {
-            const now = new Date();
-            await storage.insertCommission({
-                userId,
-                transactionId: ctx.transactionId,
-                lockingScript,
-                satoshis: xo.satoshis,
-                isRedeemed: false,
-                keyOffset: (0, utilityHelpers_1.verifyTruthy)(xo.keyOffset),
-                created_at: now,
-                updated_at: now,
-                commissionId: 0
-            }, trx);
-            const o = makeDefaultOutput(userId, ctx.transactionId, xo.satoshis, xo.vout);
-            o.lockingScript = lockingScript;
-            o.providedBy = 'storage';
-            o.purpose = 'storage-commission';
-            o.type = 'custom';
-            o.spendable = false;
-            newOutputs.push({ o, tags: [] });
-        }
-        else {
-            const o = makeDefaultOutput(userId, ctx.transactionId, xo.satoshis, xo.vout);
-            o.lockingScript = lockingScript;
-            o.basketId = xo.basket ? txBaskets[xo.basket].basketId : undefined;
-            o.customInstructions = xo.customInstructions;
-            o.outputDescription = xo.outputDescription;
-            o.providedBy = xo.providedBy;
-            o.purpose = xo.purpose || '';
-            o.type = 'custom';
-            newOutputs.push({ o, tags: xo.tags });
-        }
+        newOutputs.push(await createRequiredOutput(storage, userId, xo, ctx, txBaskets, trx));
     }
     for (const o of changeOutputs) {
         o.spendable = true;
@@ -464,6 +489,15 @@ async function createNewTxRecord(storage, userId, vargs, storageBeef, satoshis =
         txid: undefined,
         rawTx: undefined
     };
+    const brc177 = vargs.brc177;
+    if (brc177?.kind === 'protected') {
+        newTx.noSendExpiryMode = brc177.expiry.mode;
+        newTx.noSendExpiryValue = brc177.expiry.value;
+        newTx.noSendExpiryDeadline = brc177.deadline;
+        newTx.noSendExpiryState = 'preparing';
+        newTx.noSendExpiryAnchorTxid = brc177.anchorTxid;
+        newTx.noSendExpiryAnchorVout = brc177.anchorVout;
+    }
     newTx.transactionId = await storage.insertTransaction(newTx, trx);
     const labelNames = [...new Set(vargs.labels)];
     const labels = await storage.findOrInsertTxLabelsBulk(userId, labelNames, trx);
@@ -525,6 +559,22 @@ function validateRequiredOutputs(storage, userId, vargs) {
             keyOffset
         });
     }
+    const brc177 = vargs.brc177;
+    if (brc177?.kind === 'funding') {
+        vout++;
+        xoutputs.push({
+            lockingScript: '00'.repeat(25),
+            satoshis: brc177.anchorSatoshis,
+            outputDescription: '',
+            basket: undefined,
+            tags: [],
+            vout,
+            providedBy: 'storage',
+            purpose: 'change',
+            derivationSuffix: undefined,
+            keyOffset: undefined
+        });
+    }
     return xoutputs;
 }
 /**
@@ -720,6 +770,7 @@ async function traceStorageStep(storage, name, parent, attributes, callback) {
 function makeFundingParams(args) {
     const { storage, vargs, xinputs, xoutputs, changeBasket, feeModel, healthyChangeCount, compatibilityFallback } = args;
     const preferredSatoshis = Math.max(1, changeBasket.minimumDesiredUTXOValue);
+    const brc177 = vargs.brc177;
     return {
         fixedInputs: xinputs.map(input => ({
             satoshis: input.satoshis,
@@ -738,7 +789,9 @@ function makeFundingParams(args) {
         changeLockingScriptLength: 25,
         changeUnlockingScriptLength: 107,
         targetNetCount: changeBasket.numberOfDesiredUTXOs - healthyChangeCount,
-        maxChangeOutputs: storage.managedChangePolicy.maxOutputsPerAction,
+        // The planner requires a positive cap. The exact anchor leaves no surplus,
+        // and validateBrc177FundingPlan below independently rejects any change.
+        maxChangeOutputs: brc177?.kind === 'protected' ? 1 : storage.managedChangePolicy.maxOutputsPerAction,
         surplusPoolShaping: !compatibilityFallback,
         maxMigrationInputs: compatibilityFallback ? 0 : storage.managedChangePolicy.migrationInputsPerAction,
         randomVals: vargs.randomVals
@@ -747,7 +800,10 @@ function makeFundingParams(args) {
 async function buildFundingPlan(storage, context, candidates, eligibleStatuses, policyTier, compatibilityFallback, parent) {
     const [userId, vargs, xinputs, xoutputs, changeBasket, noSendChangeIn, feeModel] = context;
     const noSendIds = new Set(noSendChangeIn.map(output => output.outputId));
+    const brc177 = vargs.brc177;
     const available = candidates.filter(output => !noSendIds.has(output.outputId) && eligibleStatuses.includes(output.transactionStatus));
+    if (brc177?.kind === 'protected')
+        available.length = 0;
     const preferredSatoshis = Math.max(1, changeBasket.minimumDesiredUTXOValue);
     const healthyChangeCount = compatibilityFallback
         ? // Preserve the legacy target-count input exactly, including noSendChange
@@ -1100,6 +1156,12 @@ async function fundNewTransactionSdk(storage, userId, vargs, ctx, initialPlan, p
     };
     // Generate a derivation prefix for the payment
     const derivationPrefix = randomDerivation(16);
+    ctx.derivationPrefix = derivationPrefix;
+    for (const output of ctx.xoutputs) {
+        if (output.purpose === 'change' && output.derivationSuffix == null) {
+            output.derivationSuffix = randomDerivation(16);
+        }
+    }
     const r = {
         maxPossibleSatoshisAdjustment: gcr.maxPossibleSatoshisAdjustment,
         allocatedChange,
@@ -1134,6 +1196,21 @@ async function fundNewTransactionSdk(storage, userId, vargs, ctx, initialPlan, p
     };
     return r;
 }
+function validateBrc177FundingPlan(vargs, plan) {
+    if (vargs.brc177?.kind !== 'protected')
+        return;
+    if (plan.selected.length !== 1 || vargs.options.noSendChange.length !== 1) {
+        throw new WERR_errors_1.WERR_INVALID_OPERATION('BRC-177 protected action must use exactly one revocation anchor');
+    }
+    const selected = plan.selected[0];
+    const anchor = vargs.options.noSendChange[0];
+    if (selected.txid !== anchor.txid || selected.vout !== anchor.vout) {
+        throw new WERR_errors_1.WERR_INVALID_OPERATION('BRC-177 protected action selected a non-anchor wallet input');
+    }
+    if (plan.result.changeOutputs.length !== 0) {
+        throw new WERR_errors_1.WERR_INVALID_OPERATION('BRC-177 protected action must not create wallet change');
+    }
+}
 /**
  * Avoid returning any known raw transaction data by converting any known transaction
  * in the `beef` to txidOnly.
@@ -1166,19 +1243,77 @@ function makeKnownTxidLookup(knownTxids) {
         return knownTxids.includes(txid);
     };
 }
+function preparedBeefStorage(storage) {
+    return storage;
+}
+function appendPreparedBeefPreparation(preparations, writeEnabled, userId, rootTxids) {
+    if (!writeEnabled)
+        return;
+    preparations.push({ userId, rootTxids });
+}
+function enqueuePreparedBeefs(storage, preparations) {
+    const extension = preparedBeefStorage(storage);
+    if (typeof extension.enqueuePreparedBeef !== 'function')
+        return;
+    for (const preparation of preparations)
+        extension.enqueuePreparedBeef.call(storage, preparation);
+}
+async function loadAllocatedChangeBeef(storage, userId, txids, options, parent) {
+    const extension = preparedBeefStorage(storage);
+    const readEnabled = extension.preparedBeefReadsEnabled?.call(storage) === true;
+    const writeEnabled = extension.preparedBeefWritesEnabled?.call(storage) === true;
+    const lookup = readEnabled && typeof extension.lookupPreparedBeefs === 'function'
+        ? await extension.lookupPreparedBeefs.call(storage, userId, txids, parent)
+        : {
+            beef: new sdk_1.Beef(),
+            hitTxids: [],
+            missingTxids: [...new Set(txids)],
+            corruptCount: 0,
+            byteLength: 0
+        };
+    const beef = lookup.beef;
+    const preparations = [];
+    if (lookup.missingTxids.length > 0) {
+        const fetched = await storage.getBeefForTransactions(lookup.missingTxids, {
+            ...options,
+            mergeToBeef: undefined
+        });
+        if (lookup.hitTxids.length === 0) {
+            // Preserve the original disabled/cold path without merging into an
+            // otherwise empty BEEF solely for this optimization.
+            appendPreparedBeefPreparation(preparations, writeEnabled, userId, lookup.missingTxids);
+            return {
+                beef: fetched,
+                preparations,
+                preparedHitCount: 0,
+                canonicalFetchCount: lookup.missingTxids.length
+            };
+        }
+        beef.mergeBeef(fetched);
+        // A caller's knownTxids may leave placeholders which are unsuitable for a
+        // reusable artifact. Rebuild those roots strictly in the worker.
+        appendPreparedBeefPreparation(preparations, writeEnabled, userId, lookup.missingTxids);
+    }
+    return {
+        beef,
+        preparations,
+        preparedHitCount: lookup.hitTxids.length,
+        canonicalFetchCount: lookup.missingTxids.length
+    };
+}
 function missingAllocatedChangeTxids(allocatedChange, beef, knownTxids) {
     const hasKnownTxid = makeKnownTxidLookup(knownTxids);
     return Array.from(new Set(allocatedChange
         .map(output => (0, utilityHelpers_1.verifyTruthy)(output.txid))
         .filter(txid => beef.findTxid(txid) == null && !hasKnownTxid(txid))));
 }
-function startAllocatedChangeBeefPrefetch(storage, vargs, allocatedChange, beef, parent) {
+function startAllocatedChangeBeefPrefetch(storage, userId, vargs, allocatedChange, beef, parent) {
     if (vargs.options.returnTXIDOnly)
-        return Promise.resolve({ sourceCount: 0, txids: [] });
+        return Promise.resolve({ sourceCount: 0, txids: [], preparations: [] });
     const knownTxids = vargs.options.knownTxids ?? [];
     const missing = missingAllocatedChangeTxids(allocatedChange, beef, knownTxids);
     if (missing.length === 0)
-        return Promise.resolve({ sourceCount: 0, txids: [] });
+        return Promise.resolve({ sourceCount: 0, txids: [], preparations: [] });
     const options = {
         trustSelf: undefined,
         knownTxids,
@@ -1192,15 +1327,22 @@ function startAllocatedChangeBeefPrefetch(storage, vargs, allocatedChange, beef,
         'beef.missing_source_count': missing.length,
         'beef.storage_batch_count': missing.length === 0 ? 0 : 1
     }, async (span) => {
-        const fetched = await storage.getBeefForTransactions(missing, options);
+        const fetched = await loadAllocatedChangeBeef(storage, userId, missing, options, parent);
         span?.end({
             attributes: {
-                'beef.fetched_tx_count': fetched.txs.length,
-                'beef.fetched_bump_count': fetched.bumps.length
+                'beef.fetched_tx_count': fetched.beef.txs.length,
+                'beef.fetched_bump_count': fetched.beef.bumps.length,
+                'beef.prepared_hit_count': fetched.preparedHitCount,
+                'beef.canonical_fetch_count': fetched.canonicalFetchCount
             }
         });
         return fetched;
-    }).then(prefetched => ({ beef: prefetched, sourceCount: missing.length, txids: missing }), error => ({ error, sourceCount: missing.length, txids: missing }));
+    }).then(prefetched => ({
+        beef: prefetched.beef,
+        preparations: prefetched.preparations,
+        sourceCount: missing.length,
+        txids: missing
+    }), error => ({ error, preparations: [], sourceCount: missing.length, txids: missing }));
 }
 function sameTxids(left, right) {
     if (left.length !== right.length)
@@ -1208,7 +1350,7 @@ function sameTxids(left, right) {
     const expected = new Set(left);
     return right.every(txid => expected.has(txid));
 }
-async function mergeAllocatedChangeBeefs(storage, vargs, allocatedChange, beef, prefetch, parent) {
+async function mergeAllocatedChangeBeefs(storage, userId, vargs, allocatedChange, beef, prefetch, parent) {
     const options = {
         trustSelf: undefined,
         knownTxids: vargs.options.knownTxids,
@@ -1219,7 +1361,7 @@ async function mergeAllocatedChangeBeefs(storage, vargs, allocatedChange, beef,
         minProofLevel: undefined
     };
     if (vargs.options.returnTXIDOnly)
-        return undefined;
+        return { inputBeef: undefined, preparations: [] };
     const knownTxids = vargs.options.knownTxids ?? [];
     const requiredBeforePrefetch = missingAllocatedChangeTxids(allocatedChange, beef, knownTxids);
     const prefetched = await traceStorageStep(storage, 'wallet.storage.create_action.beef_prefetch_join', parent, { 'beef.prefetch_source_count': 0 }, async (span) => {
@@ -1235,6 +1377,7 @@ async function mergeAllocatedChangeBeefs(storage, vargs, allocatedChange, beef,
         throw prefetched.error;
     if (usePrefetch && prefetched.beef != null)
         beef.mergeBeef(prefetched.beef);
+    const preparations = usePrefetch ? [...prefetched.preparations] : [];
     // If a concurrent spender forced the funding claim to be replanned, only
     // the newly selected roots remain. The normal uncontended path is empty.
     const missing = missingAllocatedChangeTxids(allocatedChange, beef, knownTxids);
@@ -1248,7 +1391,9 @@ async function mergeAllocatedChangeBeefs(storage, vargs, allocatedChange, beef,
         'beef.prefetch_reused': usePrefetch
     }, async (span) => {
         if (missing.length > 0) {
-            fetched = await storage.getBeefForTransactions(missing, { ...options, mergeToBeef: undefined });
+            const loaded = await loadAllocatedChangeBeef(storage, userId, missing, options, parent);
+            fetched = loaded.beef;
+            preparations.push(...loaded.preparations);
         }
         span?.end({
             attributes: {
@@ -1268,7 +1413,7 @@ async function mergeAllocatedChangeBeefs(storage, vargs, allocatedChange, beef,
             }
         });
     });
-    return await traceStorageStep(storage, 'wallet.storage.create_action.beef_trim_serialize', parent, {
+    const inputBeef = await traceStorageStep(storage, 'wallet.storage.create_action.beef_trim_serialize', parent, {
         'beef.tx_count': beef.txs.length,
         'beef.bump_count': beef.bumps.length,
         'beef.known_txid_count': knownTxids.length
@@ -1277,5 +1422,6 @@ async function mergeAllocatedChangeBeefs(storage, vargs, allocatedChange, beef,
         span?.end({ attributes: { 'beef.result_bytes': result?.length ?? 0 } });
         return result;
     });
+    return { inputBeef, preparations };
 }
 //# sourceMappingURL=createAction.js.map