@cogcoin/client 0.5.12 → 0.5.14

package/dist/wallet/read/context.js

@@ -7,6 +7,7 @@ import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, } fro
 import { resolveCogcoinProcessingStartHeight } from "../../bitcoind/processing-start-height.js";
 import {} from "../../bitcoind/types.js";
 import { loadOrAutoUnlockWalletState, verifyManagedCoreWalletReplica, } from "../lifecycle.js";
+import { normalizeWalletStateRecord, persistWalletCoinControlStateIfNeeded } from "../coin-control.js";
 import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
 import { inspectMiningControlPlane } from "../mining/index.js";
 import { normalizeMiningStateRecord } from "../mining/state.js";
@@ -76,9 +77,17 @@ async function normalizeLoadedWalletStateForRead(options) {
             replacePrimary: options.loaded.source === "backup",
             rpc: createRpcClient(node.rpc),
         });
-        return {
-            source: normalized.changed ? "primary" : options.loaded.source,
+        const coinControl = await persistWalletCoinControlStateIfNeeded({
             state: normalized.state,
+            access,
+            paths: options.paths,
+            nowUnixMs: options.now,
+            replacePrimary: (normalized.changed ? "primary" : options.loaded.source) === "backup",
+            rpc: createRpcClient(node.rpc),
+        });
+        return {
+            source: coinControl.changed ? "primary" : normalized.changed ? "primary" : options.loaded.source,
+            state: coinControl.state,
         };
     }
     finally {
@@ -186,10 +195,10 @@ async function inspectWalletLocalState(options = {}) {
             return {
                 availability: "ready",
                 walletRootId: unlocked.state.walletRootId,
-                state: {
+                state: normalizeWalletStateRecord({
                     ...unlocked.state,
                     miningState: normalizeMiningStateRecord(unlocked.state.miningState),
-                },
+                }),
                 source: unlocked.source,
                 unlockUntilUnixMs: unlocked.session.unlockUntilUnixMs,
                 hasPrimaryStateFile,
@@ -226,10 +235,10 @@ async function inspectWalletLocalState(options = {}) {
         return {
             availability: "ready",
             walletRootId: loaded.state.walletRootId,
-            state: {
+            state: normalizeWalletStateRecord({
                 ...loaded.state,
                 miningState: normalizeMiningStateRecord(loaded.state.miningState),
-            },
+            }),
             source: loaded.source,
             unlockUntilUnixMs: null,
             hasPrimaryStateFile,

package/dist/wallet/reset.js

@@ -187,6 +187,8 @@ function createEntropyRetainedWalletState(previousState, nowUnixMs) {
         walletRootId,
         network: previousState.network,
         anchorValueSats: previousState.anchorValueSats,
+        proactiveReserveSats: previousState.proactiveReserveSats,
+        proactiveReserveOutpoints: previousState.proactiveReserveOutpoints,
         nextDedicatedIndex: previousState.nextDedicatedIndex,
         fundingIndex: previousState.fundingIndex,
         mnemonic: {

package/dist/wallet/state/storage.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { writeJsonFileAtomic } from "../fs/atomic.js";
+import { normalizeWalletStateRecord } from "../coin-control.js";
 import { decryptJsonWithPassphrase, decryptJsonWithSecretProvider, encryptJsonWithPassphrase, encryptJsonWithSecretProvider, } from "./crypto.js";
 async function readEnvelope(path) {
     const raw = await readFile(path, "utf8");
@@ -73,18 +74,18 @@ export async function loadWalletState(paths, access) {
     try {
         return {
             source: "primary",
-            state: typeof access === "string" || access instanceof Uint8Array
+            state: normalizeWalletStateRecord(typeof access === "string" || access instanceof Uint8Array
                 ? await decryptJsonWithPassphrase(await readEnvelope(paths.primaryPath), access)
-                : await decryptJsonWithSecretProvider(await readEnvelope(paths.primaryPath), access.provider),
+                : await decryptJsonWithSecretProvider(await readEnvelope(paths.primaryPath), access.provider)),
         };
     }
     catch (primaryError) {
         try {
             return {
                 source: "backup",
-                state: typeof access === "string" || access instanceof Uint8Array
+                state: normalizeWalletStateRecord(typeof access === "string" || access instanceof Uint8Array
                     ? await decryptJsonWithPassphrase(await readEnvelope(paths.backupPath), access)
-                    : await decryptJsonWithSecretProvider(await readEnvelope(paths.backupPath), access.provider),
+                    : await decryptJsonWithSecretProvider(await readEnvelope(paths.backupPath), access.provider)),
             };
         }
         catch {

package/dist/wallet/tx/anchor.d.ts

@@ -18,6 +18,7 @@ interface WalletAnchorRpcClient extends WalletMutationRpcClient {
 export interface AnchorDomainOptions {
     domainName: string;
     foundingMessageText?: string | null;
+    promptForFoundingMessageWhenMissing?: boolean;
     dataDir: string;
     databasePath: string;
     provider?: WalletSecretProvider;
@@ -36,6 +37,7 @@ export interface AnchorDomainResult {
     dedicatedIndex: number;
     status: "live" | "confirmed";
     reusedExisting: boolean;
+    foundingMessageText?: string | null;
 }
 export interface ClearPendingAnchorOptions {
     domainName: string;

package/dist/wallet/tx/anchor.js

@@ -9,7 +9,7 @@ import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
 import { createDefaultWalletSecretProvider, } from "../state/provider.js";
 import { serializeDomainAnchor, serializeDomainTransfer, validateDomainName, } from "../cogop/index.js";
 import { openWalletReadContext } from "../read/index.js";
-import { assertWalletMutationContextReady, buildWalletMutationTransaction, isAlreadyAcceptedError, isBroadcastUnknownError, pauseMiningForWalletMutation, saveWalletStatePreservingUnlock, unlockTemporaryBuilderLocks, } from "./common.js";
+import { assertFixedInputPrefixMatches, assertFundingInputsAfterFixedPrefix, assertWalletMutationContextReady, buildWalletMutationTransactionWithReserveFallback, getDecodedInputScriptPubKeyHex, isAlreadyAcceptedError, isBroadcastUnknownError, outpointKey, pauseMiningForWalletMutation, saveWalletStatePreservingUnlock, unlockTemporaryBuilderLocks, inputMatchesOutpoint, } from "./common.js";
 import { confirmYesNo } from "./confirm.js";
 const ACTIVE_FAMILY_STATUSES = new Set([
     "draft",
@@ -115,6 +115,11 @@ function findActiveAnchorFamilyByDomain(state, domainName) {
         && family.domainName === domainName
         && ACTIVE_FAMILY_STATUSES.has(family.status)) ?? null;
 }
+function isClearableReservedAnchorFamily(family) {
+    return family?.type === "anchor"
+        && family.status === "draft"
+        && family.currentStep === "reserved";
+}
 function findAnchorFamilyById(state, familyId) {
     return state.proactiveFamilies.find((family) => family.familyId === familyId) ?? null;
 }
@@ -215,6 +220,35 @@ function encodeFoundingMessage(foundingMessageText) {
         throw new Error(error instanceof Error ? `wallet_anchor_invalid_message_${error.message}` : "wallet_anchor_invalid_message");
     });
 }
+function extractAnchorInvalidMessageReason(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message === "wallet_anchor_invalid_message") {
+        return null;
+    }
+    if (!message.startsWith("wallet_anchor_invalid_message_")) {
+        return null;
+    }
+    const reason = message.slice("wallet_anchor_invalid_message_".length).trim();
+    return reason === "" ? null : reason;
+}
+async function resolveFoundingMessage(options) {
+    if (!options.promptForFoundingMessageWhenMissing || options.foundingMessageText != null) {
+        return encodeFoundingMessage(options.foundingMessageText ?? null);
+    }
+    for (;;) {
+        const answer = await options.prompter.prompt("Founding message (optional, press Enter to skip): ");
+        try {
+            return await encodeFoundingMessage(answer);
+        }
+        catch (error) {
+            const reason = extractAnchorInvalidMessageReason(error);
+            options.prompter.writeLine("Founding message cannot be encoded in canonical Coglex.");
+            if (reason !== null) {
+                options.prompter.writeLine(`Reason: ${reason}`);
+            }
+        }
+    }
+}
 function resolveAnchorOutpointForSender(state, senderIndex) {
     const anchoredDomain = state.domains.find((domain) => domain.currentOwnerLocalIndex === senderIndex
         && domain.canonicalChainStatus === "anchored"
@@ -456,16 +490,10 @@ function buildTx1Plan(options) {
         { [options.operation.targetIdentity.address]: satsToBtcNumber(BigInt(options.state.anchorValueSats)) },
     ];
     if (options.operation.sourceAnchorOutpoint === null) {
-        if (fundingUtxos.length === 0) {
-            throw new Error("wallet_anchor_sender_utxo_unavailable");
-        }
-        const senderInput = fundingUtxos[0];
         return {
             sender: options.operation.sourceSender,
             changeAddress: options.state.funding.address,
-            inputs: fundingUtxos.map((entry, index) => index === 0
-                ? { txid: senderInput.txid, vout: senderInput.vout }
-                : { txid: entry.txid, vout: entry.vout }),
+            fixedInputs: [],
             outputs,
             changePosition: 2,
             expectedOpReturnScriptHex: encodeOpReturnScript(serializeDomainTransfer(options.operation.chainDomain.domainId, Buffer.from(options.operation.targetIdentity.scriptPubKeyHex, "hex")).opReturnData),
@@ -474,6 +502,7 @@ function buildTx1Plan(options) {
             expectedReplacementAnchorScriptHex: null,
             expectedReplacementAnchorValueSats: null,
             allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
+            eligibleFundingOutpointKeys: new Set(fundingUtxos.map((entry) => outpointKey({ txid: entry.txid, vout: entry.vout }))),
             requiredSenderOutpoint: null,
             requiredProvisionalOutpoint: null,
             errorPrefix: "wallet_anchor_tx1",
@@ -492,10 +521,7 @@ function buildTx1Plan(options) {
     return {
         sender: options.operation.sourceSender,
         changeAddress: options.state.funding.address,
-        inputs: [
-            { txid: sourceAnchor.txid, vout: sourceAnchor.vout },
-            ...fundingUtxos.map((entry) => ({ txid: entry.txid, vout: entry.vout })),
-        ],
+        fixedInputs: [{ txid: sourceAnchor.txid, vout: sourceAnchor.vout }],
         outputs,
         changePosition: 3,
         expectedOpReturnScriptHex: encodeOpReturnScript(serializeDomainTransfer(options.operation.chainDomain.domainId, Buffer.from(options.operation.targetIdentity.scriptPubKeyHex, "hex")).opReturnData),
@@ -504,6 +530,7 @@ function buildTx1Plan(options) {
         expectedReplacementAnchorScriptHex: options.operation.sourceSender.scriptPubKeyHex,
         expectedReplacementAnchorValueSats: BigInt(options.state.anchorValueSats),
         allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
+        eligibleFundingOutpointKeys: new Set(fundingUtxos.map((entry) => outpointKey({ txid: entry.txid, vout: entry.vout }))),
         requiredSenderOutpoint: options.operation.sourceAnchorOutpoint,
         requiredProvisionalOutpoint: null,
         errorPrefix: "wallet_anchor_tx1",
@@ -535,10 +562,7 @@ function buildTx2Plan(options) {
             address: options.operation.targetIdentity.address,
         },
         changeAddress: options.state.funding.address,
-        inputs: [
-            { txid: provisional.txid, vout: provisional.vout },
-            ...fundingUtxos.map((entry) => ({ txid: entry.txid, vout: entry.vout })),
-        ],
+        fixedInputs: [{ txid: provisional.txid, vout: provisional.vout }],
         outputs: [
             { data: Buffer.from(opReturnData).toString("hex") },
             { [options.operation.targetIdentity.address]: satsToBtcNumber(BigInt(options.state.anchorValueSats)) },
@@ -550,6 +574,7 @@ function buildTx2Plan(options) {
         expectedReplacementAnchorScriptHex: null,
         expectedReplacementAnchorValueSats: null,
         allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
+        eligibleFundingOutpointKeys: new Set(fundingUtxos.map((entry) => outpointKey({ txid: entry.txid, vout: entry.vout }))),
         requiredSenderOutpoint: null,
         requiredProvisionalOutpoint: {
             txid: provisional.txid,
@@ -558,30 +583,13 @@ function buildTx2Plan(options) {
         errorPrefix: "wallet_anchor_tx2",
     };
 }
-function getDecodedInputScriptPubKeyHex(input) {
-    return input.prevout?.scriptPubKey?.hex ?? null;
-}
-function getDecodedInputVout(input) {
-    const vout = input.vout;
-    return typeof vout === "number" ? vout : null;
-}
-function inputMatchesOutpoint(input, outpoint) {
-    return input.txid === outpoint.txid && getDecodedInputVout(input) === outpoint.vout;
-}
-function assertNoUnexpectedAnchorInputs(inputs, allowedScripts, unexpectedInputErrorCode) {
-    for (const input of inputs) {
-        const scriptPubKeyHex = getDecodedInputScriptPubKeyHex(input);
-        if (scriptPubKeyHex === null || !allowedScripts.has(scriptPubKeyHex)) {
-            throw new Error(unexpectedInputErrorCode);
-        }
-    }
-}
 function validateTx1Draft(decoded, funded, plan) {
     const inputs = decoded.tx.vin;
     const outputs = decoded.tx.vout;
     if (inputs.length === 0) {
         throw new Error(`${plan.errorPrefix}_sender_input_mismatch`);
     }
+    assertFixedInputPrefixMatches(inputs, plan.fixedInputs, `${plan.errorPrefix}_sender_input_mismatch`);
     const firstInputScriptPubKeyHex = getDecodedInputScriptPubKeyHex(inputs[0]);
     if (firstInputScriptPubKeyHex !== plan.sender.scriptPubKeyHex) {
         throw new Error(`${plan.errorPrefix}_sender_input_mismatch`);
@@ -590,14 +598,14 @@ function validateTx1Draft(decoded, funded, plan) {
         if (!inputMatchesOutpoint(inputs[0], plan.requiredSenderOutpoint)) {
             throw new Error(`${plan.errorPrefix}_sender_input_mismatch`);
         }
-        if (inputs.length < 2 || getDecodedInputScriptPubKeyHex(inputs[1]) !== plan.allowedFundingScriptPubKeyHex) {
-            throw new Error(`${plan.errorPrefix}_unexpected_funding_input`);
-        }
-        assertNoUnexpectedAnchorInputs(inputs.slice(2), new Set([plan.allowedFundingScriptPubKeyHex]), `${plan.errorPrefix}_unexpected_funding_input`);
-    }
-    else {
-        assertNoUnexpectedAnchorInputs(inputs, new Set([plan.allowedFundingScriptPubKeyHex]), `${plan.errorPrefix}_unexpected_funding_input`);
     }
+    assertFundingInputsAfterFixedPrefix({
+        inputs,
+        fixedInputs: plan.fixedInputs,
+        allowedFundingScriptPubKeyHex: plan.allowedFundingScriptPubKeyHex,
+        eligibleFundingOutpointKeys: plan.eligibleFundingOutpointKeys,
+        errorCode: `${plan.errorPrefix}_unexpected_funding_input`,
+    });
     if (outputs[0]?.scriptPubKey?.hex !== plan.expectedOpReturnScriptHex) {
         throw new Error(`${plan.errorPrefix}_opreturn_mismatch`);
     }
@@ -635,15 +643,19 @@ function validateTx2Draft(decoded, funded, plan) {
     if (inputs.length === 0 || plan.requiredProvisionalOutpoint === null) {
         throw new Error(`${plan.errorPrefix}_provisional_input_mismatch`);
     }
+    assertFixedInputPrefixMatches(inputs, plan.fixedInputs, `${plan.errorPrefix}_provisional_input_mismatch`);
     const firstInputScriptPubKeyHex = getDecodedInputScriptPubKeyHex(inputs[0]);
     if (firstInputScriptPubKeyHex !== plan.sender.scriptPubKeyHex
         || !inputMatchesOutpoint(inputs[0], plan.requiredProvisionalOutpoint)) {
         throw new Error(`${plan.errorPrefix}_provisional_input_mismatch`);
     }
-    if (inputs.length < 2 || getDecodedInputScriptPubKeyHex(inputs[1]) !== plan.allowedFundingScriptPubKeyHex) {
-        throw new Error(`${plan.errorPrefix}_unexpected_funding_input`);
-    }
-    assertNoUnexpectedAnchorInputs(inputs.slice(2), new Set([plan.allowedFundingScriptPubKeyHex]), `${plan.errorPrefix}_unexpected_funding_input`);
+    assertFundingInputsAfterFixedPrefix({
+        inputs,
+        fixedInputs: plan.fixedInputs,
+        allowedFundingScriptPubKeyHex: plan.allowedFundingScriptPubKeyHex,
+        eligibleFundingOutpointKeys: plan.eligibleFundingOutpointKeys,
+        errorCode: `${plan.errorPrefix}_unexpected_funding_input`,
+    });
     if (outputs[0]?.scriptPubKey?.hex !== plan.expectedOpReturnScriptHex) {
         throw new Error(`${plan.errorPrefix}_opreturn_mismatch`);
     }
@@ -668,31 +680,27 @@ function validateTx2Draft(decoded, funded, plan) {
     }
 }
 async function buildTx1(options) {
-    return buildWalletMutationTransaction({
+    return buildWalletMutationTransactionWithReserveFallback({
         rpc: options.rpc,
         walletName: options.walletName,
+        state: options.state,
         plan: options.plan,
         validateFundedDraft: validateTx1Draft,
         finalizeErrorCode: "wallet_anchor_tx1_finalize_failed",
         mempoolRejectPrefix: "wallet_anchor_tx1_mempool_rejected",
-        builderOptions: {
-            addInputs: false,
-        },
+        reserveCandidates: options.state.proactiveReserveOutpoints,
     });
 }
 async function buildTx2(options) {
-    return buildWalletMutationTransaction({
+    return buildWalletMutationTransactionWithReserveFallback({
         rpc: options.rpc,
         walletName: options.walletName,
+        state: options.state,
         plan: options.plan,
         validateFundedDraft: validateTx2Draft,
         finalizeErrorCode: "wallet_anchor_tx2_finalize_failed",
         mempoolRejectPrefix: "wallet_anchor_tx2_mempool_rejected",
-        builderOptions: {
-            addInputs: false,
-            includeUnsafe: true,
-            minConf: 0,
-        },
+        reserveCandidates: options.state.proactiveReserveOutpoints,
     });
 }
 async function relockAnchorOutpoint(rpc, walletName, outpoint) {
@@ -998,6 +1006,7 @@ async function submitTx2(options) {
     const builtTx2 = await buildTx2({
         rpc: options.rpc,
         walletName: options.walletName,
+        state: nextState,
         plan: tx2Plan,
     });
     const broadcastingTx2 = createBroadcastingTxRecord(builtTx2);
@@ -1123,6 +1132,7 @@ async function submitTx2(options) {
         dedicatedIndex: options.operation.targetIdentity.localIndex,
         status: finalStatus,
         reusedExisting: false,
+        foundingMessageText: options.operation.foundingMessageText,
     };
 }
 function ensureSameTipHeight(context, bestHeight, errorCode) {
@@ -1147,7 +1157,11 @@ export async function anchorDomain(options) {
             paths,
             reason: "wallet-anchor",
         });
-        const message = await encodeFoundingMessage(options.foundingMessageText ?? null);
+        const message = await resolveFoundingMessage({
+            foundingMessageText: options.foundingMessageText,
+            promptForFoundingMessageWhenMissing: options.promptForFoundingMessageWhenMissing,
+            prompter: options.prompter,
+        });
         const readContext = await (options.openReadContext ?? openWalletReadContext)({
             dataDir: options.dataDir,
             databasePath: options.databasePath,
@@ -1160,6 +1174,9 @@ export async function anchorDomain(options) {
             const initialFamily = createDraftAnchorFamily(operation, nowUnixMs);
             const existingFamily = findAnchorFamilyByIntent(operation.state, initialFamily.intentFingerprintHex);
             const conflictingFamily = findActiveAnchorFamilyByDomain(operation.state, normalizedDomainName);
+            if (existingFamily === null && isClearableReservedAnchorFamily(conflictingFamily)) {
+                throw new Error(`wallet_anchor_clear_pending_first_${conflictingFamily.domainName}`);
+            }
             if (existingFamily === null && conflictingFamily !== null) {
                 throw new Error("wallet_anchor_prior_family_unresolved");
             }
@@ -1201,6 +1218,7 @@ export async function anchorDomain(options) {
                         dedicatedIndex: reconciled.family.reservedDedicatedIndex ?? existingTargetIdentity.localIndex,
                         status: reconciled.resolution,
                         reusedExisting: true,
+                        foundingMessageText: reconciled.family.foundingMessageText,
                     };
                 }
                 if (reconciled.resolution === "repair-required") {
@@ -1232,6 +1250,7 @@ export async function anchorDomain(options) {
                 const builtTx1 = await buildTx1({
                     rpc,
                     walletName,
+                    state: nextState,
                     plan: tx1Plan,
                 });
                 const broadcastingTx1 = createBroadcastingTxRecord(builtTx1);
@@ -1351,6 +1370,7 @@ export async function anchorDomain(options) {
             return {
                 ...result,
                 reusedExisting: resumedExisting,
+                foundingMessageText: result.foundingMessageText ?? operation.foundingMessageText,
             };
         }
         finally {

package/dist/wallet/tx/cog.js

@@ -7,7 +7,7 @@ import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
 import { createDefaultWalletSecretProvider, } from "../state/provider.js";
 import { serializeCogClaim, serializeCogLock, serializeCogTransfer, } from "../cogop/index.js";
 import { openWalletReadContext } from "../read/index.js";
-import { assertWalletMutationContextReady, buildWalletMutationTransaction, formatCogAmount, isAlreadyAcceptedError, isBroadcastUnknownError, pauseMiningForWalletMutation, saveWalletStatePreservingUnlock, unlockTemporaryBuilderLocks, updateMutationRecord, } from "./common.js";
+import { assertFixedInputPrefixMatches, assertFundingInputsAfterFixedPrefix, assertWalletMutationContextReady, buildWalletMutationTransactionWithReserveFallback, formatCogAmount, isAlreadyAcceptedError, isBroadcastUnknownError, outpointKey, pauseMiningForWalletMutation, saveWalletStatePreservingUnlock, unlockTemporaryBuilderLocks, updateMutationRecord, } from "./common.js";
 import { confirmTypedAcknowledgement, confirmYesNo } from "./confirm.js";
 import { getCanonicalIdentitySelector, resolveIdentityBySelector, } from "./identity-selector.js";
 import { findPendingMutationByIntent, upsertPendingMutation } from "./journal.js";
@@ -248,28 +248,17 @@ function buildPlanForCogOperation(options) {
         && entry.safe !== false);
     const outputs = [{ data: Buffer.from(options.opReturnData).toString("hex") }];
     if (options.anchorOutpoint === null) {
-        const senderUtxo = options.allUtxos.find((entry) => entry.scriptPubKey === options.sender.scriptPubKeyHex
-            && entry.confirmations >= 1
-            && entry.spendable !== false
-            && entry.safe !== false);
-        if (senderUtxo === undefined) {
-            throw new Error(`${options.errorPrefix}_sender_utxo_unavailable`);
-        }
         return {
             sender: options.sender,
             changeAddress: options.state.funding.address,
-            inputs: [
-                { txid: senderUtxo.txid, vout: senderUtxo.vout },
-                ...fundingUtxos
-                    .filter((entry) => !(entry.txid === senderUtxo.txid && entry.vout === senderUtxo.vout))
-                    .map((entry) => ({ txid: entry.txid, vout: entry.vout })),
-            ],
+            fixedInputs: [],
             outputs,
             changePosition: 1,
             expectedOpReturnScriptHex: encodeOpReturnScript(options.opReturnData),
             expectedAnchorScriptHex: null,
             expectedAnchorValueSats: null,
             allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
+            eligibleFundingOutpointKeys: new Set(fundingUtxos.map((entry) => outpointKey({ txid: entry.txid, vout: entry.vout }))),
             errorPrefix: options.errorPrefix,
         };
     }
@@ -288,9 +277,8 @@ function buildPlanForCogOperation(options) {
     return {
         sender: options.sender,
         changeAddress: options.state.funding.address,
-        inputs: [
+        fixedInputs: [
             { txid: anchorUtxo.txid, vout: anchorUtxo.vout },
-            ...fundingUtxos.map((entry) => ({ txid: entry.txid, vout: entry.vout })),
         ],
         outputs,
         changePosition: 2,
@@ -298,6 +286,7 @@ function buildPlanForCogOperation(options) {
         expectedAnchorScriptHex: options.sender.scriptPubKeyHex,
         expectedAnchorValueSats: options.anchorValueSats,
         allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
+        eligibleFundingOutpointKeys: new Set(fundingUtxos.map((entry) => outpointKey({ txid: entry.txid, vout: entry.vout }))),
         errorPrefix: options.errorPrefix,
     };
 }
@@ -307,14 +296,17 @@ function validateFundedDraft(decoded, funded, plan) {
     if (inputs.length === 0) {
         throw new Error(`${plan.errorPrefix}_missing_sender_input`);
     }
+    assertFixedInputPrefixMatches(inputs, plan.fixedInputs, `${plan.errorPrefix}_sender_input_mismatch`);
     if (inputs[0]?.prevout?.scriptPubKey?.hex !== plan.sender.scriptPubKeyHex) {
         throw new Error(`${plan.errorPrefix}_sender_input_mismatch`);
     }
-    for (let index = 1; index < inputs.length; index += 1) {
-        if (inputs[index]?.prevout?.scriptPubKey?.hex !== plan.allowedFundingScriptPubKeyHex) {
-            throw new Error(`${plan.errorPrefix}_unexpected_funding_input`);
-        }
-    }
+    assertFundingInputsAfterFixedPrefix({
+        inputs,
+        fixedInputs: plan.fixedInputs,
+        allowedFundingScriptPubKeyHex: plan.allowedFundingScriptPubKeyHex,
+        eligibleFundingOutpointKeys: plan.eligibleFundingOutpointKeys,
+        errorCode: `${plan.errorPrefix}_unexpected_funding_input`,
+    });
     if (outputs[0]?.scriptPubKey?.hex !== plan.expectedOpReturnScriptHex) {
         throw new Error(`${plan.errorPrefix}_opreturn_mismatch`);
     }
@@ -341,13 +333,15 @@ function validateFundedDraft(decoded, funded, plan) {
     }
 }
 async function buildTransaction(options) {
-    return buildWalletMutationTransaction({
+    return buildWalletMutationTransactionWithReserveFallback({
         rpc: options.rpc,
         walletName: options.walletName,
+        state: options.state,
         plan: options.plan,
         validateFundedDraft,
         finalizeErrorCode: `${options.plan.errorPrefix}_finalize_failed`,
         mempoolRejectPrefix: `${options.plan.errorPrefix}_mempool_rejected`,
+        reserveCandidates: options.state.proactiveReserveOutpoints,
     });
 }
 function createDraftMutation(options) {
@@ -699,6 +693,7 @@ export async function sendCog(options) {
             const built = await buildTransaction({
                 rpc,
                 walletName,
+                state: nextState,
                 plan: buildPlanForCogOperation({
                     state: nextState,
                     allUtxos: await rpc.listUnspent(walletName, 1),
@@ -860,6 +855,7 @@ export async function lockCogToDomain(options) {
             const built = await buildTransaction({
                 rpc,
                 walletName,
+                state: nextState,
                 plan: buildPlanForCogOperation({
                     state: nextState,
                     allUtxos: await rpc.listUnspent(walletName, 1),
@@ -1004,6 +1000,7 @@ async function runClaimLikeMutation(options, reclaim) {
             const built = await buildTransaction({
                 rpc,
                 walletName,
+                state: nextState,
                 plan: buildPlanForCogOperation({
                     state: nextState,
                     allUtxos: await rpc.listUnspent(walletName, 1),

package/dist/wallet/tx/common.d.ts

@@ -1,4 +1,4 @@
-import type { RpcDecodedPsbt, RpcFinalizePsbtResult, RpcListUnspentEntry, RpcLockedUnspent, RpcTestMempoolAcceptResult, RpcTransaction, RpcWalletCreateFundedPsbtResult, RpcWalletProcessPsbtResult } from "../../bitcoind/types.js";
+import type { RpcDecodedPsbt, RpcFinalizePsbtResult, RpcListUnspentEntry, RpcLockedUnspent, RpcTestMempoolAcceptResult, RpcTransaction, RpcVin, RpcWalletCreateFundedPsbtResult, RpcWalletProcessPsbtResult } from "../../bitcoind/types.js";
 import { type WalletSecretProvider } from "../state/provider.js";
 import type { OutpointRecord, PendingMutationRecord, PendingMutationStatus, WalletStateV1 } from "../types.js";
 import type { WalletReadContext } from "../read/index.js";
@@ -33,6 +33,8 @@ export interface BuiltWalletMutationTransaction {
     wtxid: string | null;
     temporaryBuilderLockedOutpoints: OutpointRecord[];
 }
+export interface FixedWalletInput extends OutpointRecord {
+}
 export declare function saveWalletStatePreservingUnlock(options: {
     state: WalletStateV1;
     provider: WalletSecretProvider;
@@ -49,8 +51,28 @@ export declare function updateMutationRecord(mutation: PendingMutationRecord, st
 }): PendingMutationRecord;
 export declare function unlockTemporaryBuilderLocks(rpc: Pick<WalletMutationRpcClient, "lockUnspent">, walletName: string, outpoints: OutpointRecord[]): Promise<void>;
 export declare function diffTemporaryLockedOutpoints(before: RpcLockedUnspent[], after: RpcLockedUnspent[]): OutpointRecord[];
+export declare function getDecodedInputScriptPubKeyHex(input: RpcVin): string | null;
+export declare function getDecodedInputVout(input: RpcVin): number | null;
+export declare function inputMatchesOutpoint(input: RpcVin, outpoint: OutpointRecord): boolean;
+export declare function assertFixedInputPrefixMatches(inputs: RpcVin[], fixedInputs: FixedWalletInput[], errorCode: string): void;
+export declare function assertFundingInputsAfterFixedPrefix(options: {
+    inputs: RpcVin[];
+    fixedInputs: FixedWalletInput[];
+    allowedFundingScriptPubKeyHex: string;
+    eligibleFundingOutpointKeys: Set<string>;
+    errorCode: string;
+}): void;
+export declare function reconcilePersistentPolicyLocks(options: {
+    rpc: Pick<WalletMutationRpcClient, "listLockUnspent" | "lockUnspent" | "listUnspent">;
+    walletName: string;
+    state: WalletStateV1;
+    fixedInputs: FixedWalletInput[];
+    temporarilyUnlockedOutpoints?: readonly OutpointRecord[];
+    cleanupInactiveTemporaryBuilderLocks?: boolean;
+}): Promise<void>;
 export declare function isBroadcastUnknownError(error: unknown): boolean;
 export declare function isAlreadyAcceptedError(error: unknown): boolean;
+export declare function isInsufficientFundsError(error: unknown): boolean;
 export declare function assertWalletMutationContextReady(context: WalletReadContext, errorPrefix: string): asserts context is WalletReadContext & {
     localState: {
         availability: "ready";
@@ -67,23 +89,36 @@ export declare function pauseMiningForWalletMutation(options: {
 export declare function buildWalletMutationTransaction<TPlan>(options: {
     rpc: WalletMutationRpcClient;
     walletName: string;
+    state: WalletStateV1;
     plan: TPlan & {
-        inputs: Array<{
-            txid: string;
-            vout: number;
-        }>;
+        fixedInputs: FixedWalletInput[];
         outputs: unknown[];
         changeAddress: string;
         changePosition: number;
+        allowedFundingScriptPubKeyHex: string;
+        eligibleFundingOutpointKeys: Set<string>;
     };
     validateFundedDraft(decoded: RpcDecodedPsbt, funded: RpcWalletCreateFundedPsbtResult, plan: TPlan): void;
     finalizeErrorCode: string;
     mempoolRejectPrefix: string;
     feeRate?: number;
-    builderOptions?: {
-        addInputs?: boolean;
-        includeUnsafe?: boolean;
-        minConf?: number;
-        lockUnspents?: boolean;
+    temporarilyUnlockedPolicyOutpoints?: readonly OutpointRecord[];
+}): Promise<BuiltWalletMutationTransaction>;
+export declare function buildWalletMutationTransactionWithReserveFallback<TPlan>(options: {
+    rpc: WalletMutationRpcClient;
+    walletName: string;
+    state: WalletStateV1;
+    plan: TPlan & {
+        fixedInputs: FixedWalletInput[];
+        outputs: unknown[];
+        changeAddress: string;
+        changePosition: number;
+        allowedFundingScriptPubKeyHex: string;
+        eligibleFundingOutpointKeys: Set<string>;
     };
+    validateFundedDraft(decoded: RpcDecodedPsbt, funded: RpcWalletCreateFundedPsbtResult, plan: TPlan): void;
+    finalizeErrorCode: string;
+    mempoolRejectPrefix: string;
+    feeRate?: number;
+    reserveCandidates: readonly OutpointRecord[];
 }): Promise<BuiltWalletMutationTransaction>;