@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/btc/psbt.js

@@ -0,0 +1,377 @@
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { bytesToHex } from "@noble/hashes/utils";
+import { HDKey } from "@scure/bip32";
+import * as btc from "@scure/btc-signer";
+import { TAP_LEAF_VERSION } from "@scure/btc-signer/payment.js";
+import { compareBytes, equalBytes, tagSchnorr, } from "@scure/btc-signer/utils.js";
+import { DEFAULT_MAX_FEE_RATE, networkOfAddress, scriptOf, spendVbytes, } from "./spend-rules.js";
+import { buildVaultSpend, vaultSpendSighash, } from "./vault/spend.js";
+import { BIP32_VERSIONS, COFUND_LEAF_INDEX, deriveChildFromXpub, } from "./vault/xpub.js";
+import { encodeCBFromStruct, leafScriptPolicy, tryFinalizeAny, verifyPartialSignatureAgainstMsg, } from "./witness.js";
+/** Zero aux randomness: BIP-340 permits it, and it keeps a signer's signatures deterministic. */
+const ZERO_AUX = new Uint8Array(32);
+/** A {@link BtcLeafSigner} over an account xprv (tprv off mainnet), `m/86'/coin'/0'`, held in memory. */
+export function localLeafSigner(accountXprv) {
+    const account = HDKey.fromExtendedKey(accountXprv, BIP32_VERSIONS[accountXprv.startsWith("tprv") ? "testnet" : "mainnet"]);
+    if (!account.privateKey) {
+        throw new Error("localLeafSigner takes an account's private key (xprv)");
+    }
+    const xpub = account.publicExtendedKey;
+    return {
+        xpub: () => Promise.resolve(xpub),
+        signTaprootLeaf(sighash, derivation) {
+            const key = derivation.reduce((node, index) => node.deriveChild(index), account);
+            if (!key.privateKey) {
+                throw new Error(`Could not derive the key at ${derivation.join("/")}`);
+            }
+            return Promise.resolve(schnorr.sign(sighash, key.privateKey, ZERO_AUX));
+        },
+    };
+}
+/** Change below this many sats is left to the fee: a P2TR output under it is dust. */
+export const VAULT_CHANGE_DUST = 330n;
+function vaultNetwork(vault) {
+    const net = networkOfAddress(vault.address);
+    if (!net) {
+        throw new Error(`${vault.address} is not a Bitcoin address`);
+    }
+    return net;
+}
+/** BIP-341's merkle root, from a leaf's hash and its path. */
+function merkleRootOf(leaf) {
+    return leaf.controlBlockStruct.merklePath.reduce((node, sibling) => compareBytes(node, sibling) <= 0
+        ? tagSchnorr("TapBranch", node, sibling)
+        : tagSchnorr("TapBranch", sibling, node), leaf.leafHash);
+}
+/** The key's own BIP-32 fingerprint: the origin a member's leaf keys are derived from. */
+function accountFingerprint(accountXpub) {
+    return HDKey.fromExtendedKey(accountXpub, BIP32_VERSIONS[accountXpub.startsWith("tpub") ? "testnet" : "mainnet"]).fingerprint;
+}
+/**
+ * Every leaf key with its origin: the member's account xpub (its fingerprint)
+ * and the path below it, `branch/COFUND_LEAF_INDEX`. The definition holds
+ * account xpubs, not their wallets' master fingerprints, so the origin starts
+ * at the account.
+ */
+function tapBip32Derivations(vault) {
+    const byKey = new Map();
+    for (const { leaf, branch } of vault.leaves) {
+        for (const signer of leaf.signers) {
+            const member = vault.definition.members.find(({ id }) => id === signer.id);
+            if (!member) {
+                continue;
+            }
+            const key = bytesToHex(signer.xonly);
+            const known = byKey.get(key);
+            if (known) {
+                known[1].hashes.push(leaf.leafHash);
+                continue;
+            }
+            byKey.set(key, [
+                signer.xonly,
+                {
+                    hashes: [leaf.leafHash],
+                    der: {
+                        fingerprint: accountFingerprint(member.accountXpub),
+                        path: [branch, COFUND_LEAF_INDEX],
+                    },
+                },
+            ]);
+        }
+    }
+    return [...byKey.values()];
+}
+/**
+ * The unsigned spend as a PSBT: the payees, then the extra outputs, then
+ * change back to the vault when it is not dust (the inputs less the outputs
+ * less `fee`); the inputs in their canonical order (`buildVaultSpend`, by
+ * `txid:vout`). Each input carries its prevout (`witnessUtxo`), every leaf of
+ * the vault with its control block (`tapLeafScript`), the internal key and
+ * merkle root, and each leaf key's origin (`tapBip32Derivation`).
+ */
+export function buildSpendPsbt(request) {
+    const { vault, inputs, payees, extraOutputs = [] } = request;
+    if (payees.length === 0) {
+        throw new Error("A spend pays at least one payee");
+    }
+    if (inputs.length === 0) {
+        throw new Error("A spend takes at least one of the vault's coins");
+    }
+    const fee = BigInt(request.fee);
+    if (fee < 0n) {
+        throw new Error(`The fee of ${fee} sats is negative`);
+    }
+    const net = vaultNetwork(vault);
+    const outputs = [...payees, ...extraOutputs].map(({ address, amount }) => {
+        if (BigInt(amount) <= 0n) {
+            throw new Error(`The output to ${address} pays ${amount} sats`);
+        }
+        return { script: scriptOf(net, address), amount: BigInt(amount) };
+    });
+    const seen = new Set();
+    const spendInputs = inputs.map(({ txid, vout, value }) => {
+        const id = `${txid}:${vout}`;
+        if (seen.has(id)) {
+            throw new Error(`The spend lists ${id} twice`);
+        }
+        seen.add(id);
+        return { id, txid, vout, amount: BigInt(value) };
+    });
+    const total = spendInputs.reduce((sum, { amount }) => sum + amount, 0n);
+    const paid = outputs.reduce((sum, { amount }) => sum + amount, 0n);
+    const change = total - paid - fee;
+    if (change < 0n) {
+        throw new Error(`Insufficient funds: have ${total}, need ${paid + fee}`);
+    }
+    if (change >= VAULT_CHANGE_DUST) {
+        outputs.push({ script: vault.script, amount: change });
+    }
+    const { tx } = buildVaultSpend({
+        vaultScript: vault.script,
+        inputs: spendInputs,
+        outputs,
+    });
+    const [{ leaf: anyLeaf }] = vault.leaves;
+    const taproot = {
+        tapInternalKey: anyLeaf.controlBlockStruct.internalKey,
+        tapMerkleRoot: merkleRootOf(anyLeaf),
+        tapLeafScript: vault.leaves.map(({ leaf }) => [
+            btc.TaprootControlBlock.decode(encodeCBFromStruct(leaf.controlBlockStruct)),
+            new Uint8Array([...leaf.script, TAP_LEAF_VERSION]),
+        ]),
+        tapBip32Derivation: tapBip32Derivations(vault),
+    };
+    for (let index = 0; index < tx.inputsLength; index++) {
+        tx.updateInput(index, taproot);
+    }
+    return tx.toPSBT();
+}
+function parsePsbt(psbt) {
+    return btc.Transaction.fromPSBT(psbt);
+}
+/** Each input's outpoint and amount; throws unless every input is the vault's, once. */
+function vaultInputs(tx, vault) {
+    if (tx.inputsLength === 0) {
+        throw new Error("The spend has no inputs");
+    }
+    const seen = new Set();
+    return Array.from({ length: tx.inputsLength }, (_, index) => {
+        const input = tx.getInput(index);
+        if (!input.txid || input.index === undefined) {
+            throw new Error(`Input ${index} has no outpoint`);
+        }
+        const txid = bytesToHex(input.txid);
+        const outpoint = `${txid}:${input.index}`;
+        if (!(input.witnessUtxo && equalBytes(input.witnessUtxo.script, vault.script))) {
+            throw new Error(`Input ${index} (${outpoint}) does not spend the vault ${vault.address}`);
+        }
+        if (seen.has(outpoint)) {
+            throw new Error(`The spend lists ${outpoint} twice`);
+        }
+        seen.add(outpoint);
+        return { txid, vout: input.index, value: input.witnessUtxo.amount };
+    });
+}
+/**
+ * Check a PSBT against the verified vault and what the consumer expects;
+ * throws on the first thing that does not hold:
+ *
+ * - every input spends the vault's script (`witnessUtxo`), and none twice: a
+ *   prevout the PSBT misstates only makes every signature over it invalid,
+ *   since BIP-341 commits to each prevout's script and amount;
+ * - the outputs are the payees, then the extra outputs, each its address and
+ *   amount, then at most one more: change back to the vault;
+ * - the network fee (the inputs less the outputs) is at most `maxFeeRate`
+ *   sat/vB of the spend's vsize as it is priced.
+ */
+export function checkPsbt(psbt, vault, expectations) {
+    const tx = parsePsbt(psbt);
+    const net = vaultNetwork(vault);
+    const inputs = vaultInputs(tx, vault);
+    const expected = [
+        ...expectations.payees,
+        ...(expectations.extraOutputs ?? []),
+    ];
+    const outputs = Array.from({ length: tx.outputsLength }, (_, index) => {
+        const { script, amount } = tx.getOutput(index);
+        if (!script || amount === undefined) {
+            throw new Error(`Output ${index} has no script or amount`);
+        }
+        return { script, amount };
+    });
+    for (const [index, { address, amount }] of expected.entries()) {
+        const output = outputs[index];
+        if (!(output &&
+            equalBytes(output.script, scriptOf(net, address)) &&
+            output.amount === BigInt(amount))) {
+            throw new Error(`Output ${index} is not ${amount} sats to ${address}`);
+        }
+    }
+    const rest = outputs.slice(expected.length);
+    if (rest.length > 1) {
+        throw new Error(`The spend has ${rest.length} outputs beyond the expected ones; at most one, the change, may follow them`);
+    }
+    const [change] = rest;
+    if (change && !equalBytes(change.script, vault.script)) {
+        throw new Error(`Output ${expected.length} pays ${change.amount} sats to a script that is not the vault's`);
+    }
+    const fee = inputs.reduce((sum, { value }) => sum + value, 0n) -
+        outputs.reduce((sum, { amount }) => sum + amount, 0n);
+    if (fee < 0n) {
+        throw new Error("The outputs pay more than the inputs hold");
+    }
+    const maxFeeRate = expectations.maxFeeRate ?? DEFAULT_MAX_FEE_RATE;
+    const vsize = spendVbytes(vault, inputs.length, outputs);
+    if (fee > BigInt(Math.floor(maxFeeRate * vsize))) {
+        throw new Error(`The network fee of ${fee} sats is over ${maxFeeRate} sat/vB of ${vsize} vB`);
+    }
+    const paid = (from, to) => expected.slice(from, to).map(({ address, amount }) => ({
+        address,
+        amount: BigInt(amount),
+    }));
+    return {
+        vault: vault.address,
+        inputs,
+        payees: paid(0, expectations.payees.length),
+        extraOutputs: paid(expectations.payees.length, expected.length),
+        change: change?.amount ?? 0n,
+        fee,
+        vsize,
+    };
+}
+/**
+ * The signer's BIP-340 signatures added to the PSBT (`tapScriptSig`), one per
+ * input for each leaf that holds the signer's key, over the BIP-341 sighash
+ * (SIGHASH_DEFAULT) of the spend with the verified leaf's script. First the
+ * PSBT is checked (`checkPsbt`); each signature is verified against the
+ * signer's key in the leaf before it is added.
+ */
+export async function signPsbt(psbt, vault, signer, expectations) {
+    checkPsbt(psbt, vault, expectations);
+    const xpub = await signer.xpub();
+    if (!vault.definition.members.some(({ accountXpub }) => accountXpub === xpub)) {
+        throw new Error(`The signer's xpub is not a member of vault ${vault.address}`);
+    }
+    const mine = vault.leaves.flatMap(({ leaf, branch }) => {
+        const { xonly } = deriveChildFromXpub(xpub, branch, COFUND_LEAF_INDEX);
+        return leaf.signers.some((member) => equalBytes(member.xonly, xonly))
+            ? [{ leaf, branch, xonly }]
+            : [];
+    });
+    if (mine.length === 0) {
+        throw new Error(`Vault ${vault.address} holds no leaf with the signer's key`);
+    }
+    const tx = parsePsbt(psbt);
+    for (const { leaf, branch, xonly } of mine) {
+        for (let index = 0; index < tx.inputsLength; index++) {
+            const sighash = vaultSpendSighash(tx, index, leaf.script);
+            const signature = await signer.signTaprootLeaf(sighash, [
+                branch,
+                COFUND_LEAF_INDEX,
+            ]);
+            if (!verifyPartialSignatureAgainstMsg(sighash, xonly, signature)) {
+                throw new Error(`The signer's signature over input ${index} does not verify against its key in leaf ${bytesToHex(leaf.leafHash)}`);
+            }
+            tx.updateInput(index, {
+                tapScriptSig: [
+                    [{ pubKey: xonly, leafHash: leaf.leafHash }, signature],
+                ],
+            }, true);
+        }
+    }
+    return tx.toPSBT();
+}
+/** One PSBT with the signatures of all of them; they must be the same spend of the same prevouts. */
+export function combinePsbts(psbts) {
+    const [first, ...rest] = psbts;
+    if (!first) {
+        throw new Error("No PSBTs to combine");
+    }
+    const tx = parsePsbt(first);
+    for (const psbt of rest) {
+        const other = parsePsbt(psbt);
+        const shared = Math.min(tx.inputsLength, other.inputsLength);
+        for (let index = 0; index < shared; index++) {
+            const mine = tx.getInput(index).witnessUtxo;
+            const theirs = other.getInput(index).witnessUtxo;
+            if (!(mine &&
+                theirs &&
+                mine.amount === theirs.amount &&
+                equalBytes(mine.script, theirs.script))) {
+                throw new Error(`The PSBTs disagree on input ${index}'s prevout`);
+            }
+        }
+        // Refuses a different unsigned transaction.
+        tx.combine(other);
+    }
+    return tx.toPSBT();
+}
+/** Why no leaf finalizes: each leaf's rule, and the fewest signers it has on any input. */
+function unmetLeaves(vault, partials, inputs) {
+    return vault.leaves
+        .map(({ leaf }) => {
+        const policy = leafScriptPolicy(leaf);
+        const perLeaf = partials.get(bytesToHex(leaf.leafHash));
+        const fewest = Math.min(...Array.from({ length: inputs }, (_, index) => perLeaf?.get(index)?.size ?? 0));
+        const rule = policy?.kind === "admin-required"
+            ? `its admin and ${policy.bodyThreshold} more`
+            : `${policy?.threshold} signatures`;
+        return `leaf ${bytesToHex(leaf.leafHash)} needs ${rule}, has ${fewest} signer(s) on every input`;
+    })
+        .join("; ");
+}
+/** The PSBT's `tapScriptSig`s that verify over the spend, by leaf, input and the member whose key made them. */
+function verifiedPartials(tx, candidates) {
+    const verified = Array.from({ length: tx.inputsLength }, (_, index) => (tx.getInput(index).tapScriptSig ?? []).flatMap(([{ pubKey, leafHash }, signature]) => {
+        const leaf = candidates.find((candidate) => equalBytes(candidate.leafHash, leafHash));
+        const msg = leaf && vaultSpendSighash(tx, index, leaf.script);
+        return msg && verifyPartialSignatureAgainstMsg(msg, pubKey, signature)
+            ? [{ leaf, index, pubKey, signature }]
+            : [];
+    })).flat();
+    const partials = new Map();
+    for (const { leaf, index, pubKey, signature } of verified) {
+        const key = bytesToHex(leaf.leafHash);
+        const perLeaf = partials.get(key) ?? new Map();
+        const perInput = perLeaf.get(index) ?? new Map();
+        for (const member of leaf.signers) {
+            if (equalBytes(member.xonly, pubKey)) {
+                perInput.set(member.id, signature);
+            }
+        }
+        perLeaf.set(index, perInput);
+        partials.set(key, perLeaf);
+    }
+    return partials;
+}
+/**
+ * Assemble each input's witness once one leaf has its threshold on every
+ * input, by the template's rules (`tryFinalizeAny`): k of the leaf's keys, and
+ * on an ADMINS_REQUIRED leaf its admin plus k − 1 of the rest. Only signatures
+ * that verify over the spend count. Returns the finalized PSBT, its signing
+ * fields cleared; throws when no leaf is met.
+ */
+export function finalizePsbt(psbt, vault) {
+    const tx = parsePsbt(psbt);
+    vaultInputs(tx, vault);
+    const candidates = vault.leaves.map(({ leaf }) => leaf);
+    const partials = verifiedPartials(tx, candidates);
+    const { finalized } = tryFinalizeAny({ tx, candidates, partials }, vault.definition.vaultType);
+    if (!finalized) {
+        throw new Error(`No leaf of vault ${vault.address} has its threshold on every input: ${unmetLeaves(vault, partials, tx.inputsLength)}`);
+    }
+    for (let index = 0; index < tx.inputsLength; index++) {
+        tx.updateInput(index, {
+            tapScriptSig: undefined,
+            tapLeafScript: undefined,
+            tapBip32Derivation: undefined,
+            tapInternalKey: undefined,
+            tapMerkleRoot: undefined,
+        }, true);
+    }
+    return tx.toPSBT();
+}
+/** A finalized PSBT's transaction, as raw hex to broadcast. */
+export function extractTx(psbt) {
+    return bytesToHex(parsePsbt(psbt).extract());
+}

package/dist/btc/reader.d.ts

@@ -0,0 +1,42 @@
+/** An unspent output; `value` in sats. */
+export type Utxo = {
+    txid: string;
+    vout: number;
+    value: bigint;
+    confirmed: boolean;
+};
+/** A transaction as the chain holds it: whether it is in a block, and what it pays. */
+export type BtcTx = {
+    txid: string;
+    confirmed: boolean;
+    blockHeight: number | null;
+    /** In order; `address` is null for a script with none. */
+    outputs: {
+        address: string | null;
+        value: bigint;
+    }[];
+};
+/** Where Bitcoin is read from and spends are sent: Esplora, a node, anything. */
+export type BtcReader = {
+    utxos(address: string): Promise<Utxo[]>;
+    /** Null when the transaction is unknown. */
+    tx(txid: string): Promise<BtcTx | null>;
+    /** sat/vB. */
+    feeRate(): Promise<number>;
+    /** Sends a raw transaction (hex); returns its txid. */
+    broadcast(hex: string): Promise<string>;
+};
+/**
+ * A {@link BtcReader} over an Esplora API (Blockstream's, mempool.space's, or
+ * your own electrs), with `fetch` only. `baseUrl` is the API root, e.g.
+ * `https://mempool.space/api`. The fee rate is Esplora's estimate for
+ * confirming within `feeTarget` blocks (default 1).
+ */
+export declare function esploraReader(baseUrl: string, { feeTarget }?: {
+    feeTarget?: number;
+}): BtcReader;
+/**
+ * Send a raw transaction (hex) through `reader`. Returns its txid, which must
+ * be the transaction's own.
+ */
+export declare function broadcast(hex: string, reader: BtcReader): Promise<string>;

package/dist/btc/reader.js

@@ -0,0 +1,85 @@
+import { hexToBytes } from "@noble/hashes/utils";
+import * as btc from "@scure/btc-signer";
+const TRAILING_SLASHES = /\/+$/;
+/**
+ * A {@link BtcReader} over an Esplora API (Blockstream's, mempool.space's, or
+ * your own electrs), with `fetch` only. `baseUrl` is the API root, e.g.
+ * `https://mempool.space/api`. The fee rate is Esplora's estimate for
+ * confirming within `feeTarget` blocks (default 1).
+ */
+export function esploraReader(baseUrl, { feeTarget = 1 } = {}) {
+    const root = baseUrl.replace(TRAILING_SLASHES, "");
+    const get = async (path) => {
+        const res = await fetch(`${root}${path}`);
+        if (!(res.ok || res.status === 404)) {
+            throw new Error(`Esplora GET ${path}: ${res.status} ${await res.text()}`);
+        }
+        return res;
+    };
+    return {
+        async utxos(address) {
+            const res = await get(`/address/${encodeURIComponent(address)}/utxo`);
+            if (res.status === 404) {
+                throw new Error(`Esplora does not know the address ${address}`);
+            }
+            const rows = (await res.json());
+            return rows.map(({ txid, vout, value, status }) => ({
+                txid,
+                vout,
+                value: BigInt(value),
+                confirmed: status.confirmed,
+            }));
+        },
+        async tx(txid) {
+            const res = await get(`/tx/${encodeURIComponent(txid)}`);
+            if (res.status === 404) {
+                return null;
+            }
+            const body = (await res.json());
+            return {
+                txid: body.txid,
+                confirmed: body.status.confirmed,
+                blockHeight: body.status.block_height ?? null,
+                outputs: body.vout.map((output) => ({
+                    address: output.scriptpubkey_address ?? null,
+                    value: BigInt(output.value),
+                })),
+            };
+        },
+        async feeRate() {
+            const res = await get("/fee-estimates");
+            const estimates = (await res.json());
+            const rate = estimates[String(feeTarget)];
+            if (!(typeof rate === "number" && rate > 0)) {
+                throw new Error(`Esplora has no fee estimate for ${feeTarget} block(s)`);
+            }
+            return rate;
+        },
+        async broadcast(hex) {
+            const res = await fetch(`${root}/tx`, {
+                method: "POST",
+                headers: { "content-type": "text/plain" },
+                body: hex,
+            });
+            const text = (await res.text()).trim();
+            if (!res.ok) {
+                throw new Error(`Esplora refused the transaction: ${text}`);
+            }
+            return text;
+        },
+    };
+}
+/**
+ * Send a raw transaction (hex) through `reader`. Returns its txid, which must
+ * be the transaction's own.
+ */
+export async function broadcast(hex, reader) {
+    const { id } = btc.Transaction.fromRaw(hexToBytes(hex), {
+        allowUnknownOutputs: true,
+    });
+    const txid = await reader.broadcast(hex);
+    if (txid !== id) {
+        throw new Error(`The reader broadcast ${txid}, not the transaction ${id}`);
+    }
+    return txid;
+}

package/dist/btc/select.d.ts

@@ -0,0 +1,48 @@
+import type { VerifiedBtcVault } from "./spend.ts";
+/**
+ * A margin on the raw vsize before the fee rate applies. At 1 sat/vB the fee
+ * equals the vsize, so a vsize a hair under the node's own count would be
+ * refused as below min-relay; overpaying a few sats beats a failed broadcast.
+ */
+export declare const FEE_SAFETY_MULTIPLIER = 1.125;
+/**
+ * vsize of one input of `vault`'s spend: its largest leaf's script-path
+ * witness, since which leaf a spend takes is not known before it is signed.
+ */
+export declare function vaultSpendInputVbytes(vault: VerifiedBtcVault): number;
+export type CoinSelectionRequest<T> = {
+    /** The vault's spendable coins; `value` in sats. */
+    utxos: readonly T[];
+    /** Sats paid to the payees, in all. */
+    amount: number | bigint;
+    /** sat/vB. */
+    feeRate: number;
+    /** vsize of one vault input (`vaultSpendInputVbytes`). */
+    inputVbytes: number;
+    /** Outputs paying `amount` (default 1). */
+    payeeCount?: number;
+    /** Sats of each output beyond the payees and change, such as a fee to an address. */
+    extraOutputs?: readonly (number | bigint)[];
+    /** Spend every coin, sweeping the vault into one change output, instead of only what the spend needs. */
+    consolidate?: boolean;
+};
+export type CoinSelection<T> = {
+    /** Largest first. */
+    selected: T[];
+    /** Sats the selected coins hold. */
+    total: bigint;
+    /** The network fee: the spend's vsize, with change, at `feeRate`, times {@link FEE_SAFETY_MULTIPLIER}, rounded up. */
+    fee: bigint;
+};
+/**
+ * Coins for a spend paying `amount` (and any extra outputs) at `feeRate`,
+ * priced with the vault's real input size. Largest first, it takes coins until
+ * they cover the outputs and the fee for that many inputs; with `consolidate`,
+ * it takes every coin. It locks nothing: two spends selected from one set of
+ * coins can pick the same ones.
+ *
+ * Throws when there are no coins, or they cannot cover the outputs and the fee.
+ */
+export declare function selectCoins<T extends {
+    value: number | string | bigint;
+}>(request: CoinSelectionRequest<T>): CoinSelection<T>;

package/dist/btc/select.js

@@ -0,0 +1,59 @@
+import { leafInputVbytes, vaultTxVbytes } from "./vault/tx-size.js";
+/**
+ * A margin on the raw vsize before the fee rate applies. At 1 sat/vB the fee
+ * equals the vsize, so a vsize a hair under the node's own count would be
+ * refused as below min-relay; overpaying a few sats beats a failed broadcast.
+ */
+export const FEE_SAFETY_MULTIPLIER = 1.125;
+// Every output is sized as P2TR (a 34-byte script), the largest a vault spend
+// emits: change is always P2TR, so the fee errs high when a payee's is smaller.
+const P2TR_SCRIPT_LEN = 34;
+/**
+ * vsize of one input of `vault`'s spend: its largest leaf's script-path
+ * witness, since which leaf a spend takes is not known before it is signed.
+ */
+export function vaultSpendInputVbytes(vault) {
+    return Math.max(...vault.leaves.map(({ leaf }) => leafInputVbytes(leaf)));
+}
+/**
+ * Coins for a spend paying `amount` (and any extra outputs) at `feeRate`,
+ * priced with the vault's real input size. Largest first, it takes coins until
+ * they cover the outputs and the fee for that many inputs; with `consolidate`,
+ * it takes every coin. It locks nothing: two spends selected from one set of
+ * coins can pick the same ones.
+ *
+ * Throws when there are no coins, or they cannot cover the outputs and the fee.
+ */
+export function selectCoins(request) {
+    const { utxos, feeRate, inputVbytes, payeeCount = 1, extraOutputs = [], consolidate = false, } = request;
+    if (!utxos || utxos.length === 0) {
+        throw new Error("No available UTXOs found for the specified vault");
+    }
+    if (!(Number.isFinite(feeRate) && feeRate > 0)) {
+        throw new Error(`The fee rate must be above 0 sat/vB, not ${feeRate}`);
+    }
+    // Payees, the extra outputs, and change.
+    const outputScriptLens = Array.from({ length: payeeCount + extraOutputs.length + 1 }, () => P2TR_SCRIPT_LEN);
+    const feeFor = (nIn) => BigInt(Math.ceil(feeRate *
+        vaultTxVbytes({ inputVbytes, nIn, outputScriptLens }) *
+        FEE_SAFETY_MULTIPLIER));
+    const needed = BigInt(request.amount) +
+        extraOutputs.reduce((sum, value) => sum + BigInt(value), 0n);
+    const sorted = utxos
+        .slice()
+        .sort((a, b) => Number(b.value) - Number(a.value));
+    const selected = [];
+    let total = 0n;
+    for (const utxo of sorted) {
+        if (!consolidate && total >= needed + feeFor(selected.length)) {
+            break;
+        }
+        selected.push(utxo);
+        total += BigInt(utxo.value);
+    }
+    const fee = feeFor(selected.length);
+    if (total < needed + fee) {
+        throw new Error("balance too low for requested amount + fee");
+    }
+    return { selected, total, fee };
+}

package/dist/btc/spend-rules.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What every spend check shares (`checkBtcSpend`, `checkPsbt`): the vault's
+ * network, an address as a script on it, and the spend's size as the fee is
+ * priced. Internal: not part of `./btc`.
+ */
+import * as btc from "@scure/btc-signer";
+import type { VerifiedBtcVault } from "./spend.ts";
+/** The network fee's default ceiling, in sat/vB. */
+export declare const DEFAULT_MAX_FEE_RATE = 1000;
+/**
+ * The network of a bech32 address, by its prefix; undefined when it is none
+ * of Bitcoin's. Read when called, not when the module loads: an app test that
+ * mocks part of `@scure/btc-signer` still loads this entry.
+ */
+export declare function networkOfAddress(address: string): typeof btc.NETWORK | undefined;
+export declare function scriptOf(net: typeof btc.NETWORK, address: string): Uint8Array;
+/**
+ * The spend's vsize as the app prices its fee: every input witnessed by the
+ * vault's largest leaf, since which leaf the spend takes is not known before
+ * it is signed.
+ */
+export declare function spendVbytes(vault: VerifiedBtcVault, inputs: number, outputs: {
+    script: Uint8Array;
+}[]): number;

package/dist/btc/spend-rules.js

@@ -0,0 +1,43 @@
+/**
+ * What every spend check shares (`checkBtcSpend`, `checkPsbt`): the vault's
+ * network, an address as a script on it, and the spend's size as the fee is
+ * priced. Internal: not part of `./btc`.
+ */
+import * as btc from "@scure/btc-signer";
+import { vaultSpendInputVbytes } from "./select.js";
+import { vaultTxVbytes } from "./vault/tx-size.js";
+/** The network fee's default ceiling, in sat/vB. */
+export const DEFAULT_MAX_FEE_RATE = 1000;
+/**
+ * The network of a bech32 address, by its prefix; undefined when it is none
+ * of Bitcoin's. Read when called, not when the module loads: an app test that
+ * mocks part of `@scure/btc-signer` still loads this entry.
+ */
+export function networkOfAddress(address) {
+    const networks = {
+        bc: btc.NETWORK,
+        tb: btc.TEST_NETWORK,
+        bcrt: { ...btc.TEST_NETWORK, bech32: "bcrt" },
+    };
+    return networks[address.slice(0, address.lastIndexOf("1"))];
+}
+export function scriptOf(net, address) {
+    try {
+        return btc.OutScript.encode(btc.Address(net).decode(address));
+    }
+    catch {
+        throw new Error(`${address} is not an address on this network`);
+    }
+}
+/**
+ * The spend's vsize as the app prices its fee: every input witnessed by the
+ * vault's largest leaf, since which leaf the spend takes is not known before
+ * it is signed.
+ */
+export function spendVbytes(vault, inputs, outputs) {
+    return vaultTxVbytes({
+        inputVbytes: vaultSpendInputVbytes(vault),
+        nIn: inputs,
+        outputScriptLens: outputs.map(({ script }) => script.length),
+    });
+}