@cogcoin/client 1.1.8 → 1.1.10

package/dist/wallet/tx/anchor.js

@@ -1,494 +1 @@
-import { createHash, randomBytes } from "node:crypto";
-import { encodeSentence } from "@cogcoin/scoring";
-import { lookupDomain } from "@cogcoin/indexer/queries";
-import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
-import { createRpcClient } from "../../bitcoind/node.js";
-import {} from "../runtime.js";
-import {} from "../state/provider.js";
-import { serializeDomainAnchor, validateDomainName, } from "../cogop/index.js";
-import { openWalletReadContext } from "../read/index.js";
-import { assertWalletMutationContextReady, buildWalletMutationTransactionWithReserveFallback, createWalletMutationFeeMetadata, mergeFixedWalletInputs, outpointKey, saveWalletStatePreservingUnlock, unlockTemporaryBuilderLocks, updateMutationRecord, } from "./common.js";
-import { executeWalletMutationOperation, persistWalletMutationState, publishWalletMutation, resolveExistingWalletMutation, } from "./executor.js";
-import { upsertPendingMutation } from "./journal.js";
-function normalizeDomainName(domainName) {
-    const normalized = domainName.trim().toLowerCase();
-    if (normalized.length === 0) {
-        throw new Error("wallet_anchor_missing_domain");
-    }
-    validateDomainName(normalized);
-    return normalized;
-}
-function encodeOpReturnScript(payload) {
-    if (payload.length <= 75) {
-        return Buffer.concat([
-            Buffer.from([0x6a, payload.length]),
-            Buffer.from(payload),
-        ]).toString("hex");
-    }
-    return Buffer.concat([
-        Buffer.from([0x6a, 0x4c, payload.length]),
-        Buffer.from(payload),
-    ]).toString("hex");
-}
-function satsToBtcNumber(value) {
-    return Number(value) / 100_000_000;
-}
-function valueToSats(value) {
-    const text = typeof value === "number" ? value.toFixed(8) : value;
-    const match = /^(-?)(\d+)(?:\.(\d{0,8}))?$/.exec(text.trim());
-    if (match == null) {
-        throw new Error(`wallet_anchor_invalid_amount_${text}`);
-    }
-    const sign = match[1] === "-" ? -1n : 1n;
-    const whole = BigInt(match[2] ?? "0");
-    const fraction = BigInt((match[3] ?? "").padEnd(8, "0"));
-    return sign * ((whole * 100000000n) + fraction);
-}
-function createIntentFingerprint(parts) {
-    return createHash("sha256")
-        .update(parts.map((part) => String(part)).join("\n"))
-        .digest("hex");
-}
-function sortUtxos(entries) {
-    return entries
-        .slice()
-        .sort((left, right) => right.amount - left.amount
-        || left.txid.localeCompare(right.txid)
-        || left.vout - right.vout);
-}
-function isSpendableFundingUtxo(entry, fundingScriptPubKeyHex) {
-    return entry.scriptPubKey === fundingScriptPubKeyHex
-        && entry.confirmations >= 1
-        && entry.spendable !== false
-        && entry.safe !== false;
-}
-function encodeFoundingMessage(foundingMessageText) {
-    const trimmed = foundingMessageText?.trim() ?? "";
-    if (trimmed === "") {
-        return Promise.resolve({
-            text: null,
-            payloadHex: null,
-        });
-    }
-    return encodeSentence(trimmed)
-        .then((payload) => ({
-        text: trimmed,
-        payloadHex: Buffer.from(payload).toString("hex"),
-    }))
-        .catch((error) => {
-        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}`);
-            }
-        }
-    }
-}
-async function confirmDirectAnchor(prompter, options) {
-    prompter.writeLine(`You are anchoring "${options.domainName}".`);
-    prompter.writeLine(`Wallet address: ${options.walletAddress}`);
-    prompter.writeLine("Anchoring publishes a standalone DOMAIN_ANCHOR from the local wallet address.");
-    if (options.foundingMessageText !== null) {
-        prompter.writeLine("The founding message bytes will be public in mempool and on-chain.");
-        prompter.writeLine(`Founding message: ${options.foundingMessageText}`);
-    }
-    const answer = (await prompter.prompt("Type the domain name to continue: ")).trim();
-    if (answer !== options.domainName) {
-        throw new Error("wallet_anchor_confirmation_rejected");
-    }
-}
-function buildDirectAnchorPlan(options) {
-    const fundingUtxos = sortUtxos(options.allUtxos.filter((entry) => isSpendableFundingUtxo(entry, options.state.funding.scriptPubKeyHex)));
-    const foundingPayload = options.foundingMessagePayloadHex === null
-        ? undefined
-        : Buffer.from(options.foundingMessagePayloadHex, "hex");
-    const opReturnData = serializeDomainAnchor(options.domainId, foundingPayload).opReturnData;
-    return {
-        fixedInputs: [],
-        outputs: [{ data: Buffer.from(opReturnData).toString("hex") }],
-        changeAddress: options.state.funding.address,
-        changePosition: 1,
-        expectedOpReturnScriptHex: encodeOpReturnScript(opReturnData),
-        allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
-        eligibleFundingOutpointKeys: new Set(fundingUtxos.map((entry) => outpointKey({ txid: entry.txid, vout: entry.vout }))),
-    };
-}
-function validateDirectAnchorDraft(decoded, funded, plan) {
-    const outputs = decoded.tx.vout;
-    if (outputs[0]?.scriptPubKey?.hex !== plan.expectedOpReturnScriptHex) {
-        throw new Error("wallet_anchor_opreturn_mismatch");
-    }
-    if (funded.changepos === -1) {
-        if (outputs.length !== 1) {
-            throw new Error("wallet_anchor_unexpected_output_count");
-        }
-        return;
-    }
-    if (funded.changepos !== plan.changePosition || outputs.length !== 2) {
-        throw new Error("wallet_anchor_change_position_mismatch");
-    }
-    if (outputs[funded.changepos]?.scriptPubKey?.hex !== plan.allowedFundingScriptPubKeyHex) {
-        throw new Error("wallet_anchor_change_output_mismatch");
-    }
-}
-function createDraftAnchorMutation(options) {
-    const existing = options.existing ?? null;
-    if (existing !== null) {
-        return {
-            ...existing,
-            kind: "anchor",
-            domainName: options.domainName,
-            parentDomainName: null,
-            senderScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
-            senderLocalIndex: 0,
-            intentFingerprintHex: options.intentFingerprintHex,
-            status: "draft",
-            lastUpdatedAtUnixMs: options.nowUnixMs,
-            attemptedTxid: null,
-            attemptedWtxid: null,
-            ...createWalletMutationFeeMetadata(options.feeSelection),
-            temporaryBuilderLockedOutpoints: [],
-        };
-    }
-    return {
-        mutationId: randomBytes(12).toString("hex"),
-        kind: "anchor",
-        domainName: options.domainName,
-        parentDomainName: null,
-        senderScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
-        senderLocalIndex: 0,
-        intentFingerprintHex: options.intentFingerprintHex,
-        status: "draft",
-        createdAtUnixMs: options.nowUnixMs,
-        lastUpdatedAtUnixMs: options.nowUnixMs,
-        attemptedTxid: null,
-        attemptedWtxid: null,
-        ...createWalletMutationFeeMetadata(options.feeSelection),
-        temporaryBuilderLockedOutpoints: [],
-    };
-}
-function upsertAnchoredDomainRecord(options) {
-    const domains = options.state.domains.slice();
-    const existingIndex = domains.findIndex((entry) => entry.name === options.domainName);
-    const current = existingIndex >= 0 ? domains[existingIndex] : null;
-    const nextRecord = {
-        name: options.domainName,
-        domainId: options.domainId,
-        currentOwnerScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
-        canonicalChainStatus: "anchored",
-        foundingMessageText: options.foundingMessageText ?? current?.foundingMessageText ?? null,
-        birthTime: current?.birthTime ?? options.state.lastWrittenAtUnixMs,
-    };
-    if (existingIndex >= 0) {
-        domains[existingIndex] = nextRecord;
-    }
-    else {
-        domains.push(nextRecord);
-    }
-    return {
-        ...options.state,
-        domains,
-    };
-}
-function anchorConfirmedOnSnapshot(options) {
-    const chainDomain = lookupDomain(options.snapshot.state, options.domainName);
-    if (chainDomain === null || !chainDomain.anchored) {
-        return false;
-    }
-    const ownerHex = Buffer.from(chainDomain.ownerScriptPubKey).toString("hex");
-    return ownerHex === options.state.funding.scriptPubKeyHex
-        || (options.state.localScriptPubKeyHexes ?? []).includes(ownerHex);
-}
-async function saveState(options) {
-    return persistWalletMutationState(options);
-}
-async function reconcilePendingAnchorMutation(options) {
-    if (options.mutation.status === "repair-required") {
-        return {
-            state: options.state,
-            mutation: options.mutation,
-            resolution: "repair-required",
-        };
-    }
-    if (options.context.snapshot !== null && anchorConfirmedOnSnapshot({
-        snapshot: options.context.snapshot,
-        state: options.state,
-        domainName: options.mutation.domainName,
-    })) {
-        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
-        const confirmedMutation = updateMutationRecord(options.mutation, "confirmed", options.nowUnixMs, {
-            temporaryBuilderLockedOutpoints: [],
-        });
-        const chainDomain = lookupDomain(options.context.snapshot.state, options.mutation.domainName);
-        const nextState = upsertAnchoredDomainRecord({
-            state: upsertPendingMutation(options.state, confirmedMutation),
-            domainName: options.mutation.domainName,
-            domainId: chainDomain?.domainId ?? 0,
-            foundingMessageText: options.foundingMessageText,
-        });
-        return {
-            state: await saveState({
-                state: nextState,
-                provider: options.provider,
-                nowUnixMs: options.nowUnixMs,
-                paths: options.paths,
-            }),
-            mutation: confirmedMutation,
-            resolution: "confirmed",
-        };
-    }
-    if (options.mutation.attemptedTxid !== null) {
-        const mempool = await options.rpc.getRawMempool().catch(() => []);
-        if (mempool.includes(options.mutation.attemptedTxid)) {
-            await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
-            const liveMutation = updateMutationRecord(options.mutation, "live", options.nowUnixMs, {
-                temporaryBuilderLockedOutpoints: [],
-            });
-            const domainId = (options.context.snapshot === null
-                ? null
-                : lookupDomain(options.context.snapshot.state, options.mutation.domainName)?.domainId)
-                ?? options.state.domains.find((domain) => domain.name === options.mutation.domainName)?.domainId
-                ?? 0;
-            const nextState = upsertAnchoredDomainRecord({
-                state: upsertPendingMutation(options.state, liveMutation),
-                domainName: options.mutation.domainName,
-                domainId,
-                foundingMessageText: options.foundingMessageText,
-            });
-            return {
-                state: await saveState({
-                    state: nextState,
-                    provider: options.provider,
-                    nowUnixMs: options.nowUnixMs,
-                    paths: options.paths,
-                }),
-                mutation: liveMutation,
-                resolution: "live",
-            };
-        }
-    }
-    if (options.mutation.status === "broadcast-unknown"
-        || options.mutation.status === "live"
-        || options.mutation.status === "draft"
-        || options.mutation.status === "broadcasting") {
-        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
-        const canceledMutation = updateMutationRecord(options.mutation, "canceled", options.nowUnixMs, {
-            temporaryBuilderLockedOutpoints: [],
-        });
-        const nextState = upsertPendingMutation(options.state, canceledMutation);
-        return {
-            state: await saveState({
-                state: nextState,
-                provider: options.provider,
-                nowUnixMs: options.nowUnixMs,
-                paths: options.paths,
-            }),
-            mutation: canceledMutation,
-            resolution: "not-seen",
-        };
-    }
-    return {
-        state: options.state,
-        mutation: options.mutation,
-        resolution: "continue",
-    };
-}
-function ensureSameTipHeight(context, bestHeight, errorCode) {
-    if (context.snapshot?.tip?.height !== bestHeight) {
-        throw new Error(errorCode);
-    }
-}
-export async function anchorDomain(options) {
-    if (!options.prompter.isInteractive) {
-        throw new Error("wallet_anchor_requires_tty");
-    }
-    const normalizedDomainName = normalizeDomainName(options.domainName);
-    const execution = await executeWalletMutationOperation({
-        ...options,
-        controlLockPurpose: "wallet-anchor",
-        preemptionReason: "wallet-anchor",
-        async resolveOperation(readContext) {
-            assertWalletMutationContextReady(readContext, "wallet_anchor");
-            const message = await resolveFoundingMessage({
-                foundingMessageText: options.foundingMessageText,
-                promptForFoundingMessageWhenMissing: options.promptForFoundingMessageWhenMissing,
-                prompter: options.prompter,
-            });
-            const state = readContext.localState.state;
-            const chainDomain = lookupDomain(readContext.snapshot.state, normalizedDomainName);
-            if (chainDomain === null) {
-                throw new Error("wallet_anchor_domain_not_found");
-            }
-            if (chainDomain.anchored) {
-                throw new Error("wallet_anchor_domain_already_anchored");
-            }
-            const ownerHex = Buffer.from(chainDomain.ownerScriptPubKey).toString("hex");
-            const localScriptHexes = new Set([
-                state.funding.scriptPubKeyHex,
-                ...(state.localScriptPubKeyHexes ?? []),
-            ]);
-            if (!localScriptHexes.has(ownerHex)) {
-                throw new Error("wallet_anchor_owner_not_locally_controlled");
-            }
-            if (state.funding.address.trim() === "") {
-                throw new Error("wallet_anchor_owner_identity_not_supported");
-            }
-            return {
-                state,
-                normalizedDomainName,
-                chainDomain,
-                message,
-            };
-        },
-        createIntentFingerprint(operation) {
-            return createIntentFingerprint([
-                "anchor",
-                operation.state.walletRootId,
-                operation.normalizedDomainName,
-                operation.state.funding.scriptPubKeyHex,
-                operation.message.payloadHex ?? "",
-            ]);
-        },
-        async resolveExistingMutation({ operation, existingMutation, execution }) {
-            if (existingMutation === null) {
-                return { state: operation.state, replacementFixedInputs: null, result: null };
-            }
-            return resolveExistingWalletMutation({
-                existingMutation,
-                execution,
-                repairRequiredErrorCode: "wallet_anchor_repair_required",
-                reconcileExistingMutation: (mutation) => reconcilePendingAnchorMutation({
-                    state: operation.state,
-                    mutation,
-                    provider: execution.provider,
-                    nowUnixMs: execution.nowUnixMs,
-                    paths: execution.paths,
-                    rpc: execution.rpc,
-                    walletName: execution.walletName,
-                    context: execution.readContext,
-                    foundingMessageText: operation.message.text,
-                }),
-                createReuseResult: ({ mutation, resolution, fees }) => ({
-                    domainName: operation.normalizedDomainName,
-                    txid: mutation.attemptedTxid ?? "unknown",
-                    status: resolution,
-                    reusedExisting: true,
-                    foundingMessageText: operation.message.text,
-                    fees,
-                }),
-            });
-        },
-        confirm({ operation }) {
-            return confirmDirectAnchor(options.prompter, {
-                domainName: operation.normalizedDomainName,
-                walletAddress: operation.state.funding.address,
-                foundingMessageText: operation.message.text,
-            });
-        },
-        createDraftMutation({ operation, existingMutation, execution, intentFingerprintHex }) {
-            return {
-                mutation: createDraftAnchorMutation({
-                    state: operation.state,
-                    domainName: operation.normalizedDomainName,
-                    intentFingerprintHex,
-                    nowUnixMs: execution.nowUnixMs,
-                    feeSelection: execution.feeSelection,
-                    existing: existingMutation ?? null,
-                }),
-                prepared: null,
-            };
-        },
-        async build({ operation, state, execution, replacementFixedInputs }) {
-            const directAnchorPlan = buildDirectAnchorPlan({
-                state,
-                allUtxos: await execution.rpc.listUnspent(execution.walletName, 1),
-                domainId: operation.chainDomain.domainId,
-                foundingMessagePayloadHex: operation.message.payloadHex,
-            });
-            return buildWalletMutationTransactionWithReserveFallback({
-                rpc: execution.rpc,
-                walletName: execution.walletName,
-                state,
-                plan: {
-                    ...directAnchorPlan,
-                    fixedInputs: mergeFixedWalletInputs(directAnchorPlan.fixedInputs, replacementFixedInputs),
-                },
-                validateFundedDraft: validateDirectAnchorDraft,
-                finalizeErrorCode: "wallet_anchor_finalize_failed",
-                mempoolRejectPrefix: "wallet_anchor_mempool_rejected",
-                feeRate: execution.feeSelection.feeRateSatVb,
-            });
-        },
-        publish({ operation, state, execution, built, mutation }) {
-            return publishWalletMutation({
-                rpc: execution.rpc,
-                walletName: execution.walletName,
-                snapshotHeight: execution.readContext.snapshot?.tip?.height ?? null,
-                built,
-                mutation,
-                state,
-                provider: execution.provider,
-                nowUnixMs: execution.nowUnixMs,
-                paths: execution.paths,
-                errorPrefix: "wallet_anchor",
-                async afterAccepted({ state: acceptedState, broadcastingMutation, built, nowUnixMs }) {
-                    const finalStatus = anchorConfirmedOnSnapshot({
-                        snapshot: execution.readContext.snapshot,
-                        state: acceptedState,
-                        domainName: operation.normalizedDomainName,
-                    }) ? "confirmed" : "live";
-                    const finalMutation = updateMutationRecord(broadcastingMutation, finalStatus, nowUnixMs, {
-                        attemptedTxid: built.txid,
-                        attemptedWtxid: built.wtxid,
-                        temporaryBuilderLockedOutpoints: [],
-                    });
-                    return {
-                        state: upsertAnchoredDomainRecord({
-                            state: upsertPendingMutation(acceptedState, finalMutation),
-                            domainName: operation.normalizedDomainName,
-                            domainId: operation.chainDomain.domainId,
-                            foundingMessageText: operation.message.text,
-                        }),
-                        mutation: finalMutation,
-                        status: finalStatus,
-                    };
-                },
-            });
-        },
-        createResult({ operation, mutation, built, status, reusedExisting, fees }) {
-            return {
-                domainName: operation.normalizedDomainName,
-                txid: mutation.attemptedTxid ?? built?.txid ?? "unknown",
-                status: status,
-                reusedExisting,
-                foundingMessageText: operation.message.text,
-                fees,
-            };
-        },
-    });
-    return execution.result;
-}
+export * from "./anchor/index.js";

package/dist/wallet/tx/bitcoin-transfer/confirm.d.ts

@@ -0,0 +1,7 @@
+import type { WalletPrompter } from "../../lifecycle.js";
+export declare function confirmBitcoinTransfer(prompter: WalletPrompter, options: {
+    senderAddress: string;
+    recipientAddress: string;
+    amountSats: bigint;
+    assumeYes?: boolean;
+}): Promise<void>;

package/dist/wallet/tx/bitcoin-transfer/confirm.js

@@ -0,0 +1,11 @@
+import { confirmYesNo } from "../confirm.js";
+export async function confirmBitcoinTransfer(prompter, options) {
+    prompter.writeLine(`You are sending ${options.amountSats.toString()} sats.`);
+    prompter.writeLine(`Wallet address: ${options.senderAddress}`);
+    prompter.writeLine(`Recipient: ${options.recipientAddress}`);
+    await confirmYesNo(prompter, "This will publish a standard Bitcoin payment from the wallet address.", {
+        assumeYes: options.assumeYes,
+        errorCode: "wallet_bitcoin_transfer_confirmation_rejected",
+        requiresTtyErrorCode: "wallet_bitcoin_transfer_requires_tty",
+    });
+}

package/dist/wallet/tx/bitcoin-transfer/index.d.ts

@@ -0,0 +1,5 @@
+import { type TransferBitcoinOptions } from "./intent.js";
+import { type BitcoinTransferResult } from "./result.js";
+export type { TransferBitcoinOptions } from "./intent.js";
+export type { BitcoinTransferResult } from "./result.js";
+export declare function transferBitcoin(options: TransferBitcoinOptions): Promise<BitcoinTransferResult>;

package/dist/wallet/tx/bitcoin-transfer/index.js

@@ -0,0 +1,112 @@
+import { attachOrStartManagedBitcoindService } from "../../../bitcoind/service.js";
+import { createRpcClient } from "../../../bitcoind/node.js";
+import { acquireFileLock } from "../../fs/lock.js";
+import { openWalletReadContext } from "../../read/index.js";
+import { resolveWalletRuntimePathsForTesting } from "../../runtime.js";
+import { createDefaultWalletSecretProvider, } from "../../state/provider.js";
+import { assertWalletBitcoinTransferContextReady, buildWalletMutationTransaction, isAlreadyAcceptedError, isBroadcastUnknownError, isInsufficientFundsError, outpointKey, pauseMiningForWalletMutation, unlockTemporaryBuilderLocks, } from "../common.js";
+import { confirmBitcoinTransfer } from "./confirm.js";
+import { buildPlanForBitcoinTransfer, resolveBitcoinTransferIntent, } from "./intent.js";
+import { validateFundedBitcoinTransfer } from "./plan.js";
+import { createBitcoinTransferResult } from "./result.js";
+export async function transferBitcoin(options) {
+    const intent = resolveBitcoinTransferIntent(options);
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const controlLock = await acquireFileLock(paths.walletControlLockPath, {
+        purpose: "wallet-bitcoin-transfer",
+        walletRootId: null,
+    });
+    try {
+        const miningPreemption = await pauseMiningForWalletMutation({
+            paths,
+            reason: "wallet-bitcoin-transfer",
+        });
+        const readContext = await (options.openReadContext ?? openWalletReadContext)({
+            dataDir: options.dataDir,
+            databasePath: options.databasePath,
+            secretProvider: provider,
+            walletControlLockHeld: true,
+            paths,
+        });
+        try {
+            assertWalletBitcoinTransferContextReady(readContext, "wallet_bitcoin_transfer");
+            const state = readContext.localState.state;
+            if (state.funding.scriptPubKeyHex === intent.recipientScriptPubKeyHex) {
+                throw new Error("wallet_bitcoin_transfer_self_transfer");
+            }
+            await confirmBitcoinTransfer(options.prompter, {
+                senderAddress: state.funding.address,
+                recipientAddress: intent.recipientAddress,
+                amountSats: intent.amountSats,
+                assumeYes: options.assumeYes,
+            });
+            const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
+                dataDir: options.dataDir,
+                chain: "main",
+                startHeight: 0,
+                walletRootId: state.walletRootId,
+            });
+            const rpc = (options.rpcFactory ?? createRpcClient)(node.rpc);
+            const walletName = state.managedCoreWallet.walletName;
+            const allUtxos = await rpc.listUnspent(walletName, 1);
+            const plan = buildPlanForBitcoinTransfer({
+                state,
+                allUtxos,
+                recipientAddress: intent.recipientAddress,
+                recipientScriptPubKeyHex: intent.recipientScriptPubKeyHex,
+                amountSats: intent.amountSats,
+                outpointKey,
+            });
+            let built;
+            try {
+                built = await buildWalletMutationTransaction({
+                    rpc,
+                    walletName,
+                    state,
+                    plan,
+                    validateFundedDraft: validateFundedBitcoinTransfer,
+                    finalizeErrorCode: "wallet_bitcoin_transfer_finalize_failed",
+                    mempoolRejectPrefix: "wallet_bitcoin_transfer_mempool_reject",
+                });
+            }
+            catch (error) {
+                if (isInsufficientFundsError(error)) {
+                    throw new Error("wallet_bitcoin_transfer_insufficient_funds", { cause: error });
+                }
+                throw error;
+            }
+            try {
+                await rpc.sendRawTransaction(built.rawHex);
+            }
+            catch (error) {
+                if (!isAlreadyAcceptedError(error)) {
+                    if (isInsufficientFundsError(error)) {
+                        throw new Error("wallet_bitcoin_transfer_insufficient_funds", { cause: error });
+                    }
+                    if (isBroadcastUnknownError(error)) {
+                        throw new Error("wallet_bitcoin_transfer_broadcast_unknown", { cause: error });
+                    }
+                    throw error;
+                }
+            }
+            finally {
+                await unlockTemporaryBuilderLocks(rpc, walletName, built.temporaryBuilderLockedOutpoints);
+            }
+            return createBitcoinTransferResult({
+                state,
+                built,
+                amountSats: intent.amountSats,
+                recipientAddress: intent.recipientAddress,
+                recipientScriptPubKeyHex: intent.recipientScriptPubKeyHex,
+            });
+        }
+        finally {
+            await readContext.close();
+            await miningPreemption.release();
+        }
+    }
+    finally {
+        await controlLock.release();
+    }
+}

package/dist/wallet/tx/bitcoin-transfer/intent.d.ts

@@ -0,0 +1,52 @@
+import type { RpcListUnspentEntry } from "../../../bitcoind/types.js";
+import { attachOrStartManagedBitcoindService } from "../../../bitcoind/service.js";
+import { createRpcClient } from "../../../bitcoind/node.js";
+import type { WalletPrompter } from "../../lifecycle.js";
+import { openWalletReadContext } from "../../read/index.js";
+import type { WalletRuntimePaths } from "../../runtime.js";
+import type { WalletSecretProvider } from "../../state/provider.js";
+import type { WalletStateV1 } from "../../types.js";
+import type { FixedWalletInput, WalletMutationRpcClient } from "../common.js";
+export interface WalletBitcoinTransferRpcClient extends WalletMutationRpcClient {
+    sendRawTransaction(hex: string): Promise<string>;
+}
+export interface TransferBitcoinOptions {
+    amountSatsText: string;
+    target: string;
+    dataDir: string;
+    databasePath: string;
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    assumeYes?: boolean;
+    paths?: WalletRuntimePaths;
+    openReadContext?: typeof openWalletReadContext;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletBitcoinTransferRpcClient;
+}
+export interface BitcoinTransferIntent {
+    amountSats: bigint;
+    recipientAddress: string;
+    recipientScriptPubKeyHex: string;
+}
+export interface BitcoinTransferPlan {
+    fixedInputs: FixedWalletInput[];
+    outputs: unknown[];
+    changeAddress: string;
+    changePosition: number | null;
+    allowedFundingScriptPubKeyHex: string;
+    eligibleFundingOutpointKeys: Set<string>;
+    recipientScriptPubKeyHex: string;
+    amountSats: bigint;
+}
+export declare function resolveBitcoinTransferIntent(options: TransferBitcoinOptions): BitcoinTransferIntent;
+export declare function buildPlanForBitcoinTransfer(options: {
+    state: WalletStateV1;
+    allUtxos: RpcListUnspentEntry[];
+    recipientAddress: string;
+    recipientScriptPubKeyHex: string;
+    amountSats: bigint;
+    outpointKey(outpoint: {
+        txid: string;
+        vout: number;
+    }): string;
+}): BitcoinTransferPlan;