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

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

@@ -2,7 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setDisableDoubleSpendCheckForTest = setDisableDoubleSpendCheckForTest;
 exports.createAction = createAction;
+exports.validateRequiredOutputs = validateRequiredOutputs;
+exports.validateRequiredInputs = validateRequiredInputs;
+const validationHelpers_1 = require("@bsv/sdk/wallet/validationHelpers");
 const sdk_1 = require("@bsv/sdk");
+const utils_1 = require("@bsv/sdk/primitives/utils");
 const generateChange_1 = require("./generateChange");
 const StorageProvider_1 = require("../StorageProvider");
 const WERR_errors_1 = require("../../sdk/WERR_errors");
@@ -14,6 +18,7 @@ const offsetKey_1 = require("./offsetKey");
 const sdk_2 = require("../../sdk");
 const managedChange_1 = require("./managedChange");
 const actionPlanning_1 = require("./actionPlanning");
+const beefForTxids_1 = require("../../utility/beefForTxids");
 let disableDoubleSpendCheckForTest = true;
 function setDisableDoubleSpendCheckForTest(v) {
     disableDoubleSpendCheckForTest = v;
@@ -49,6 +54,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...
@@ -68,7 +76,7 @@ async function createActionCore(storage, auth, vargs, parent) {
      * - Create result inputs with source locking scripts
      * - Create result outputs with new locking scripts.
      * - Create and return result.
-    */
+     */
     const userId = auth.userId;
     const validated = await traceStorageStep(storage, 'wallet.storage.create_action.validate', parent, {
         'action.fixed_input_count': vargs.inputs.length,
@@ -98,13 +106,14 @@ async function createActionCore(storage, auth, vargs, parent) {
     const { storageBeef, beef, xinputs, xoutputs, changeBasket, noSendChangeIn } = validated;
     const feeModel = (0, StorageProvider_1.validateStorageFeeModel)(storage.feeModel);
     logger?.log(`validated fee model ${JSON.stringify(feeModel)}`);
-    const initialFundingPlan = await prepareFundingPlan(storage, [userId, vargs, xinputs, xoutputs, changeBasket, noSendChangeIn, feeModel, parent]);
+    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;
@@ -137,7 +146,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);
@@ -157,7 +170,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,
@@ -176,9 +189,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;
     }
@@ -351,7 +368,7 @@ function describeNewOutput(o, tags, txBaskets) {
     const changeVout = o.change && o.purpose === 'change' && o.providedBy === 'storage' ? o.vout : undefined;
     const ro = {
         vout: (0, utilityHelpers_1.verifyInteger)(o.vout),
-        satoshis: sdk_1.Validation.validateSatoshis(o.satoshis, 'o.satoshis'),
+        satoshis: (0, validationHelpers_1.validateSatoshis)(o.satoshis, 'o.satoshis'),
         lockingScript: o.lockingScript == null ? '' : (0, utilityHelpers_noBuffer_1.asString)(o.lockingScript),
         providedBy: (0, utilityHelpers_1.verifyTruthy)(o.providedBy),
         purpose: o.purpose || undefined,
@@ -378,6 +395,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))];
@@ -387,39 +447,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;
@@ -463,6 +491,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);
@@ -524,6 +561,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;
 }
 /**
@@ -549,7 +602,7 @@ function validateRequiredOutputs(storage, userId, vargs) {
  */
 async function validateRequiredInputs(storage, userId, vargs) {
     // stampLog(vargs, `start storage verifyInputBeef`)
-    const beef = new sdk_1.Beef();
+    let beef = new sdk_1.Beef();
     if (vargs.inputs.length === 0)
         return { storageBeef: beef, beef, xinputs: [] };
     if (vargs.inputBEEF != null)
@@ -572,6 +625,10 @@ async function validateRequiredInputs(storage, userId, vargs) {
         inputsByTxid[input.outpoint.txid] ||= [];
         inputsByTxid[input.outpoint.txid].push(input);
     }
+    // inputBEEF is an untrusted proof-data container, not a declaration of
+    // additional inputs. Retain only the transactions needed to prove the
+    // declared inputs so unrelated branches are neither validated nor stored.
+    beef = (0, beefForTxids_1.beefForTxids)(beef, Object.keys(inputsByTxid));
     const localKnownInputTxids = {};
     for (const [txid, txInputs] of Object.entries(inputsByTxid)) {
         localKnownInputTxids[txid] = txInputs.every(input => {
@@ -582,7 +639,7 @@ async function validateRequiredInputs(storage, userId, vargs) {
     await validateBeefTxidOnlyEntries(beef, inputsByTxid, trustSelf, storage);
     await ensureBeefContainsAllInputTxids(beef, inputsByTxid, localKnownInputTxids, trustSelf, storage);
     if (!(await beef.verify(await storage.getServices().getChainTracker(), true))) {
-        console.log(`verifyInputBeef failed, inputBEEF failed to verify.\n${beef.toLogString()}\n`);
+        vargs.logger?.error('inputBEEF failed independent validation');
         throw new WERR_errors_1.WERR_INVALID_PARAMETER('inputBEEF', 'valid Beef when factoring options.trustSelf');
     }
     const storageBeef = beef.clone();
@@ -633,7 +690,7 @@ function applyStoredInputScript(output, input, vargs) {
     if (!disableDoubleSpendCheckForTest && !output.spendable && !vargs.isNoSend) {
         throw new WERR_errors_1.WERR_INVALID_PARAMETER(`${txid}.${vout}`, 'spendable output unless noSend is true');
     }
-    input.satoshis = sdk_1.Validation.validateSatoshis(output.satoshis, 'output.satoshis');
+    input.satoshis = (0, validationHelpers_1.validateSatoshis)(output.satoshis, 'output.satoshis');
     input.lockingScript = sdk_1.Script.fromBinary((0, utilityHelpers_noBuffer_1.asArray)(output.lockingScript));
 }
 async function applyBeefInputScript(storage, beef, input) {
@@ -652,7 +709,7 @@ async function applyBeefInputScript(storage, beef, input) {
         throw new WERR_errors_1.WERR_INVALID_PARAMETER(`${txid}.${vout}`, 'valid outpoint');
     }
     const sourceOutput = beefTx.tx.outputs[vout];
-    input.satoshis = sdk_1.Validation.validateSatoshis(sourceOutput.satoshis, 'so.satoshis');
+    input.satoshis = (0, validationHelpers_1.validateSatoshis)(sourceOutput.satoshis, 'so.satoshis');
     input.lockingScript = sourceOutput.lockingScript;
 }
 async function resolveInputScript(storage, userId, vargs, input, beef, preloadedOutputsByOutpoint) {
@@ -697,8 +754,8 @@ async function validateNoSendChange(storage, userId, vargs, changeBasket) {
     return r;
 }
 function fundingPlanSatoshis(plan) {
-    return plan.result.changeOutputs.reduce((sum, output) => sum + output.satoshis, 0) -
-        plan.selected.reduce((sum, output) => sum + output.satoshis, 0);
+    return (plan.result.changeOutputs.reduce((sum, output) => sum + output.satoshis, 0) -
+        plan.selected.reduce((sum, output) => sum + output.satoshis, 0));
 }
 class FundingClaimConflict extends Error {
     conflict;
@@ -712,7 +769,10 @@ async function traceStorageStep(storage, name, parent, attributes, callback) {
         return await callback();
     return await storage.telemetry.withSpan(name, { component: 'wallet-storage', parent: parent?.context, attributes }, async (span) => await callback(span));
 }
-function makeFundingParams(vargs, xinputs, xoutputs, changeBasket, feeModel, availableChangeCount) {
+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,
@@ -723,40 +783,65 @@ function makeFundingParams(vargs, xinputs, xoutputs, changeBasket, feeModel, ava
             lockingScriptLength: output.lockingScript.length / 2
         })),
         feeModel,
-        changeInitialSatoshis: Math.max(1, changeBasket.minimumDesiredUTXOValue),
-        changeFirstSatoshis: Math.max(1, Math.round(changeBasket.minimumDesiredUTXOValue / 4)),
+        changeInitialSatoshis: preferredSatoshis,
+        // The final compatibility shape uses the allocator's economic floor. This
+        // remains at least as permissive as every historical basket preference,
+        // including an exact 144/32 basket that has just migrated to 144/5000.
+        changeFirstSatoshis: compatibilityFallback ? 1 : preferredSatoshis,
         changeLockingScriptLength: 25,
         changeUnlockingScriptLength: 107,
-        targetNetCount: changeBasket.numberOfDesiredUTXOs - availableChangeCount,
+        targetNetCount: changeBasket.numberOfDesiredUTXOs - healthyChangeCount,
+        // 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
     };
 }
-async function prepareFundingPlan(storage, context) {
-    const [userId, vargs, xinputs, xoutputs, changeBasket, noSendChangeIn, feeModel, parent, trx] = context;
-    const excludeSending = !vargs.isDelayed;
-    const candidates = await traceStorageStep(storage, 'wallet.storage.create_action.funding_candidates', parent, { 'funding.exclude_sending': excludeSending }, async (span) => {
-        const outputs = await storage.findAvailableManagedChangeInputCandidates(userId, changeBasket.basketId, excludeSending, trx);
-        span?.end({
-            attributes: {
-                'funding.candidate_count': outputs.length,
-                'funding.candidate_satoshis': outputs.reduce((sum, output) => sum + output.satoshis, 0)
-            }
-        });
-        return outputs;
-    });
+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 available = candidates.filter(output => !noSendIds.has(output.outputId));
-    // Preserve the legacy target-net-count input: noSendChange was included in
-    // countChangeInputs before it was consumed by the allocator.
-    const params = makeFundingParams(vargs, xinputs, xoutputs, changeBasket, feeModel, candidates.length);
+    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
+            // that is removed from the allocator below but still belongs to this tier.
+            candidates.filter(output => eligibleStatuses.includes(output.transactionStatus)).length
+        : candidates.filter(output => output.satoshis >= preferredSatoshis).length;
+    const params = makeFundingParams({
+        storage,
+        vargs,
+        xinputs,
+        xoutputs,
+        changeBasket,
+        feeModel,
+        healthyChangeCount,
+        compatibilityFallback
+    });
+    const noSendStatuses = await storage.findTransactionStatusesByIds(userId, noSendChangeIn.map(output => output.transactionId));
+    const plannedNoSend = noSendChangeIn.map(output => ({
+        outputId: output.outputId,
+        transactionId: output.transactionId,
+        satoshis: output.satoshis,
+        txid: output.txid,
+        vout: output.vout,
+        transactionStatus: noSendStatuses.get(output.transactionId) ?? 'nosend'
+    }));
+    const claimStatuses = [...new Set([...eligibleStatuses, ...plannedNoSend.map(output => output.transactionStatus)])];
     return await traceStorageStep(storage, 'wallet.storage.create_action.funding_plan', parent, {
         'funding.candidate_count': available.length,
-        'funding.no_send_change_count': noSendChangeIn.length
+        'funding.no_send_change_count': noSendChangeIn.length,
+        'funding.policy_tier': policyTier,
+        'funding.compatibility_fallback': compatibilityFallback
     }, async (span) => {
         const allocated = new Map();
         const availableSelector = new actionPlanning_1.CanonicalChangeSelector(available);
-        const noSend = [...noSendChangeIn];
-        const noSendById = new Map(noSendChangeIn.map(output => [output.outputId, output]));
+        const noSend = [...plannedNoSend];
+        const noSendById = new Map(plannedNoSend.map(output => [output.outputId, output]));
         const allocate = async (targetSatoshis, exactSatoshis) => {
             let output = noSend.pop();
             output ??= availableSelector.take(targetSatoshis, exactSatoshis);
@@ -789,21 +874,137 @@ async function prepareFundingPlan(storage, context) {
             params,
             result,
             selected,
-            availableChangeCount: candidates.length
+            availableChangeCount: candidates.length,
+            eligibleStatuses: claimStatuses,
+            policyTier,
+            compatibilityFallback
         };
     });
 }
+async function fundingPlanSerializedCost(storage, plan, knownTxids) {
+    const txids = [...new Set(plan.selected.map(candidate => (0, utilityHelpers_1.verifyTruthy)(candidate.txid)))];
+    if (txids.length === 0)
+        return plan.result.size;
+    try {
+        const beef = await storage.getBeefForTransactions(txids, {
+            knownTxids,
+            ignoreStorage: false,
+            ignoreServices: true,
+            ignoreNewProven: false
+        });
+        return plan.result.size + beef.toUint8Array().length;
+    }
+    catch {
+        return Number.MAX_SAFE_INTEGER;
+    }
+}
+const FUNDING_TIERS = [
+    { policyTier: 'completed', statuses: ['completed'] },
+    { policyTier: 'unproven', statuses: ['completed', 'unproven'] },
+    { policyTier: 'sending', statuses: ['completed', 'unproven', 'sending'] }
+];
+async function resolveFundingCandidates(storage, userId, basketId, parent, trx) {
+    const rawCandidates = await traceStorageStep(storage, 'wallet.storage.create_action.funding_candidates', parent, { 'funding.include_pending': true }, async (span) => {
+        const outputs = await storage.findAvailableManagedChangeInputCandidates(userId, basketId, false, trx);
+        span?.end({
+            attributes: {
+                'funding.candidate_count': outputs.length,
+                'funding.candidate_satoshis': outputs.reduce((sum, output) => sum + output.satoshis, 0),
+                'funding.completed_candidate_count': outputs.filter(output => output.transactionStatus === 'completed')
+                    .length,
+                'funding.unproven_candidate_count': outputs.filter(output => output.transactionStatus === 'unproven').length,
+                'funding.sending_candidate_count': outputs.filter(output => output.transactionStatus === 'sending').length
+            }
+        });
+        return outputs;
+    });
+    const missingStatusIds = rawCandidates
+        .filter(output => output.transactionStatus == null)
+        .map(output => output.transactionId);
+    const missingStatuses = await storage.findTransactionStatusesByIds(userId, missingStatusIds, trx);
+    const candidates = rawCandidates.map(output => ({
+        ...output,
+        transactionStatus: output.transactionStatus ?? missingStatuses.get(output.transactionId)
+    }));
+    if (candidates.some(output => output.transactionStatus == null)) {
+        throw new WERR_errors_1.WERR_INTERNAL('managed change candidate is missing its source transaction status');
+    }
+    return candidates;
+}
+async function buildFundingPlanForTier(storage, context, candidates, tier, parent) {
+    try {
+        return {
+            plan: await buildFundingPlan(storage, context, candidates, tier.statuses, tier.policyTier, false, parent)
+        };
+    }
+    catch (error) {
+        if (!(error instanceof WERR_errors_1.WERR_INSUFFICIENT_FUNDS))
+            throw error;
+    }
+    // Pool shaping is optional. Before widening ancestry to unproven or sending
+    // parents, retry the same status tier with the former funding shape. This is
+    // the one-way compatibility guarantee: a preferred minimum can never
+    // manufacture starvation or force a pending chain.
+    try {
+        return {
+            plan: await buildFundingPlan(storage, context, candidates, tier.statuses, 'compatibility', true, parent)
+        };
+    }
+    catch (error) {
+        if (!(error instanceof WERR_errors_1.WERR_INSUFFICIENT_FUNDS))
+            throw error;
+        return { fundingError: error };
+    }
+}
+function firstPlanNeedsNoPendingComparison(storage, plan) {
+    const threshold = storage.managedChangePolicy.pendingComparisonInputs;
+    return threshold === -1 || plan.selected.length <= threshold;
+}
+async function chooseLowestSerializedFundingPlan(storage, plans, knownTxids) {
+    let chosen = plans[0];
+    let chosenCost = await fundingPlanSerializedCost(storage, chosen, knownTxids);
+    for (const alternative of plans.slice(1)) {
+        const cost = await fundingPlanSerializedCost(storage, alternative, knownTxids);
+        if (cost < chosenCost) {
+            chosen = alternative;
+            chosenCost = cost;
+        }
+    }
+    return chosen;
+}
+async function prepareFundingPlanWithLiquidityPolicy(storage, context, parent, trx) {
+    const [userId, vargs, , , changeBasket] = context;
+    const candidates = await resolveFundingCandidates(storage, userId, changeBasket.basketId, parent, trx);
+    const successful = [];
+    let fundingError;
+    for (const tier of FUNDING_TIERS) {
+        const attempted = await buildFundingPlanForTier(storage, context, candidates, tier, parent);
+        fundingError = attempted.fundingError ?? fundingError;
+        const plan = attempted.plan;
+        if (plan != null) {
+            successful.push(plan);
+            if (successful.length === 1 && firstPlanNeedsNoPendingComparison(storage, plan))
+                return plan;
+        }
+    }
+    if (successful.length > 0) {
+        if (successful.length === 1)
+            return successful[0];
+        return await chooseLowestSerializedFundingPlan(storage, successful, vargs.options.knownTxids);
+    }
+    if (fundingError != null)
+        throw fundingError;
+    throw new WERR_errors_1.WERR_INTERNAL('funding policy produced neither a plan nor an error');
+}
 async function claimFundingPlan(storage, request) {
-    const [userId, basketId, excludeSending, transactionId, noSendChangeIn, plan, trx] = request;
+    const [userId, basketId, eligibleStatuses, transactionId, noSendChangeIn, plan, trx] = request;
     if (plan.selected.length === 0) {
         return { outputs: [], sourceTransactionCount: 0, hydratedScriptCount: 0, scriptSourceTransactionCount: 0 };
     }
     const noSendIds = new Set(noSendChangeIn.map(output => output.outputId));
-    const statuses = ['completed', 'unproven'];
-    if (!excludeSending)
-        statuses.push('sending');
-    const claim = await storage.transaction(async (claimTrx) => {
-        const currentById = await storage.findFundingOutputsForUpdate(userId, plan.selected.map(output => output.outputId), statuses, claimTrx);
+    const claim = await storage
+        .transaction(async (claimTrx) => {
+        const currentById = await storage.findFundingOutputsForUpdate(userId, plan.selected.map(output => output.outputId), eligibleStatuses, claimTrx);
         const transactionIds = [...new Set(Object.values(currentById).map(output => output.transactionId))];
         const claimed = [];
         for (const planned of plan.selected) {
@@ -827,7 +1028,8 @@ async function claimFundingPlan(storage, request) {
             output.spentBy = transactionId;
         }
         return { outputs: claimed, sourceTransactionCount: transactionIds.length };
-    }, trx).catch(error => {
+    }, trx)
+        .catch(error => {
         if (error instanceof FundingClaimConflict)
             return { conflict: error.conflict };
         throw error;
@@ -843,9 +1045,12 @@ async function claimFundingPlan(storage, request) {
 }
 async function hydrateFundingInputScripts(storage, outputs, trx) {
     const missing = outputs.filter(output => output.lockingScript?.length !== output.scriptLength &&
-        output.scriptLength != null && output.scriptLength > 0 &&
-        output.scriptOffset != null && output.scriptOffset > 0 &&
-        output.txid != null && output.txid !== '');
+        output.scriptLength != null &&
+        output.scriptLength > 0 &&
+        output.scriptOffset != null &&
+        output.scriptOffset > 0 &&
+        output.txid != null &&
+        output.txid !== '');
     if (missing.length === 0)
         return { hydratedScriptCount: 0, scriptSourceTransactionCount: 0 };
     const byTxid = new Map();
@@ -890,7 +1095,7 @@ async function fundNewTransactionSdk(storage, userId, vargs, ctx, initialPlan, p
             const claim = await claimFundingPlan(storage, [
                 userId,
                 ctx.changeBasket.basketId,
-                !vargs.isDelayed,
+                plan.eligibleStatuses,
                 ctx.transactionId,
                 ctx.noSendChangeIn,
                 plan,
@@ -912,17 +1117,7 @@ async function fundNewTransactionSdk(storage, userId, vargs, ctx, initialPlan, p
                 throw new WERR_errors_1.WERR_INVALID_PARAMETER('noSendChange', 'outputs that remain spendable during action planning');
             }
             retryCount++;
-            plan = await prepareFundingPlan(storage, [
-                userId,
-                vargs,
-                ctx.xinputs,
-                ctx.xoutputs,
-                ctx.changeBasket,
-                ctx.noSendChangeIn,
-                ctx.feeModel,
-                parent,
-                trx
-            ]);
+            plan = await prepareFundingPlanWithLiquidityPolicy(storage, [userId, vargs, ctx.xinputs, ctx.xoutputs, ctx.changeBasket, ctx.noSendChangeIn, ctx.feeModel], parent, trx);
         }
         throw new WERR_errors_1.WERR_INVALID_OPERATION('wallet funding changed repeatedly during action planning; retry createAction');
     });
@@ -959,10 +1154,16 @@ async function fundNewTransactionSdk(storage, userId, vargs, ctx, initialPlan, p
             for (let i = 0; i < count; i++)
                 val.push(rand(0, 255));
         }
-        return sdk_1.Utils.toBase64(val);
+        return (0, utils_1.toBase64)(val);
     };
     // 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,
@@ -997,6 +1198,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.
@@ -1029,19 +1245,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,
@@ -1055,15 +1329,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)
@@ -1071,7 +1352,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,
@@ -1082,7 +1363,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) => {
@@ -1098,6 +1379,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);
@@ -1111,7 +1393,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: {
@@ -1131,7 +1415,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
@@ -1140,5 +1424,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