@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/btc/vault/participant-order.js

@@ -0,0 +1,135 @@
+/**
+ * Canonical participant ordering for account-based BTC vaults.
+ *
+ * A vault's taproot address is not stored anywhere — `Vault.contractId` holds
+ * only the roster (xpubs + roles), and every read path re-derives the address
+ * from it. Participant order decides the order of pushed keys inside the
+ * `CHECKSIGADD` tapscript, and for ADMINS_REQUIRED it also decides which admin
+ * owns which derivation branch (`2 * leafIdx`). So the comparator used to order
+ * the roster is part of the address: change it and a live vault silently
+ * repoints at an address nobody funded.
+ *
+ * That makes `String.prototype.localeCompare` unusable here, which is what this
+ * module replaces. With no explicit locale it resolves the runtime's default
+ * collation — the browser's UI language on the client, `LANG`/`LC_ALL` (or ICU's
+ * `en-US` fallback) on the server. Base58 is mixed-case alphanumeric, and
+ * several CLDR tailorings reorder plain ASCII:
+ *
+ *   - `cs` treats `ch` as one letter sorting after `h`, so `ch…` > `d…`
+ *   - `da` / `nb` fold `aa` to `å`, which sorts after `z`
+ *   - `et` reorders `z` before `t`…`w`; `lt` reorders `y`; `hu` has digraphs
+ *
+ * Measured against a corpus of realistic `tpub…` strings, `lt` disagrees with
+ * `en` on ~3.5% of pairs and `et` on ~1.5%. A vault created by the server and
+ * displayed to a Czech-locale browser therefore rendered two different valid
+ * bech32m addresses for one `contractId`.
+ *
+ * Both orderings below are pure, total and frozen. Neither consults ICU, so
+ * they return the same result in every runtime, browser locale and ICU version.
+ */
+import { compareCodepoint } from "./canonical-order.js";
+/**
+ * Ordering rule a vault's address was derived under.
+ *
+ * Persisted in the `contractId` so a vault always re-derives under the rule it
+ * was created with. An absent field means {@link ORDERING_ICU_EN_V1} — every
+ * vault created before this field existed was ordered by `localeCompare`.
+ */
+export const ORDERING_ICU_EN_V1 = "icu-en-v1";
+/** Ordering rule for vaults created from now on. */
+export const ORDERING_XPUB_CODEPOINT_V2 = "role-then-xpub-codepoint-v2";
+/** The rule new vaults are created under. */
+export const CURRENT_PARTICIPANT_ORDERING = ORDERING_XPUB_CODEPOINT_V2;
+/**
+ * Read the ordering rule off a deserialized contract.
+ *
+ * Fails OPEN to v1 rather than throwing: an unrecognised value can only come
+ * from a contract written by a newer revision, and v1 is what every vault
+ * predating the field used. Callers that must not guess should compare the
+ * derived address against a known-good one instead.
+ */
+export function participantOrderingOf(value) {
+    return value === ORDERING_XPUB_CODEPOINT_V2
+        ? ORDERING_XPUB_CODEPOINT_V2
+        : ORDERING_ICU_EN_V1;
+}
+// v2 orders by code point — `compareCodepoint` from `./canonical-order.ts`,
+// the same comparator every other consensus-critical sort in the app uses.
+// Base58 is ASCII, so code-unit order is byte order: digits, then `A`–`Z`, then
+// `a`–`z`. Preferred over comparing the decoded 78-byte extended key because it
+// cannot fail — a malformed xpub still orders deterministically instead of
+// throwing inside a read path that renders a page.
+// ── v1: frozen replica of the ICU en collation ───────────────────────────
+/**
+ * Primary collation weight of one Base58 character.
+ *
+ * CLDR root sorts digits before letters and gives a letter one weight
+ * regardless of case — case is a tertiary difference, applied only after the
+ * whole primary sequence ties. That two-level structure is why a per-character
+ * rank table cannot stand in for this: under a flat table a case difference at
+ * position 0 would outrank a letter difference at position 1, and ICU orders
+ * `aC` after `Ab` precisely because it does not.
+ */
+function primaryWeight(code) {
+    // "1"–"9" → 1–9. Base58 has no "0".
+    if (code >= 0x31 && code <= 0x39) {
+        return code - 0x30;
+    }
+    // "A"–"Z" → 100–125, case-folded onto the same weights as "a"–"z".
+    if (code >= 0x41 && code <= 0x5a) {
+        return 100 + (code - 0x41);
+    }
+    // "a"–"z" → 100–125.
+    if (code >= 0x61 && code <= 0x7a) {
+        return 100 + (code - 0x61);
+    }
+    // Anything else (never present in Base58) keeps a stable relative position
+    // by its own code point, above every letter.
+    return 1000 + code;
+}
+function isUpperAscii(code) {
+    return code >= 0x41 && code <= 0x5a;
+}
+/**
+ * The ordering that `localeCompare()` produced for Base58 strings on an
+ * `en`-family runtime — the rule every pre-v2 vault address was built under.
+ *
+ * Exists ONLY so those vaults keep re-deriving the address their UTXOs are
+ * locked to. Do not use it for anything new; new vaults use
+ * {@link compareCodepoint} via {@link ORDERING_XPUB_CODEPOINT_V2}.
+ *
+ * Verified equal to `Intl.Collator` for `en-US`, `en-GB`, `de-DE`, `fr-FR`,
+ * `ja-JP`, `zh-CN`, `ar-EG`, `he-IL`, `ru-RU`, `el-GR` and `hi-IN` across
+ * exhaustive two-character Base58 pairs and randomised full-length `tpub`
+ * corpora — see `participant-order.test.ts`. Those locales all inherit root
+ * collation for ASCII; the tailorings that diverge (`cs`, `da`, `nb`, `et`,
+ * `lt`, `hu`) are the bug this replaces, not behaviour to reproduce.
+ */
+export function compareBase58IcuEnV1(a, b) {
+    const shared = Math.min(a.length, b.length);
+    // Primary pass: letter and digit identity across the whole string.
+    for (let i = 0; i < shared; i++) {
+        const diff = primaryWeight(a.charCodeAt(i)) - primaryWeight(b.charCodeAt(i));
+        if (diff !== 0) {
+            return diff < 0 ? -1 : 1;
+        }
+    }
+    if (a.length !== b.length) {
+        return a.length < b.length ? -1 : 1;
+    }
+    // Tertiary pass: case, lowercase before uppercase.
+    for (let i = 0; i < shared; i++) {
+        const aUpper = isUpperAscii(a.charCodeAt(i));
+        const bUpper = isUpperAscii(b.charCodeAt(i));
+        if (aUpper !== bUpper) {
+            return aUpper ? 1 : -1;
+        }
+    }
+    return 0;
+}
+/** The xpub comparator for a given ordering rule. */
+export function xpubComparatorFor(ordering) {
+    return ordering === ORDERING_XPUB_CODEPOINT_V2
+        ? compareCodepoint
+        : compareBase58IcuEnV1;
+}

package/dist/btc/vault/script.d.ts

@@ -0,0 +1,13 @@
+import { type ScriptType } from "@scure/btc-signer";
+/**
+ * The k-of-n CHECKSIG/CHECKSIGADD ladder, as an op list.
+ *
+ * This is the single implementation used by both the direct k-of-n builder and
+ * the ADMINS_REQUIRED builder in `build.ts`.
+ *
+ * Keys must already be sorted: ordering is the caller's policy decision, and it
+ * is mirrored into `Leaf.signers`, which is what the witness assembler walks.
+ */
+export declare function kOfNOps(xonlys: Uint8Array[], k: number): ScriptType;
+/** Serialise the k-of-n ladder to tapscript bytes. */
+export declare function buildKofNScript(xonlys: Uint8Array[], k: number): Uint8Array;

package/dist/btc/vault/script.js

@@ -0,0 +1,39 @@
+import { Script } from "@scure/btc-signer";
+import { BTC_VAULT_MAX_PARTICIPANTS } from "./limits.js";
+/**
+ * The k-of-n CHECKSIG/CHECKSIGADD ladder, as an op list.
+ *
+ * This is the single implementation used by both the direct k-of-n builder and
+ * the ADMINS_REQUIRED builder in `build.ts`.
+ *
+ * Keys must already be sorted: ordering is the caller's policy decision, and it
+ * is mirrored into `Leaf.signers`, which is what the witness assembler walks.
+ */
+export function kOfNOps(xonlys, k) {
+    // Script.encode truncates fractional numbers in the OP_1..OP_16 range.
+    if (!Number.isInteger(k) || k < 1 || k > xonlys.length) {
+        throw new Error(`invalid threshold ${k}: must be an integer in 1..${xonlys.length}`);
+    }
+    // Cofund caps every vault at fourteen participants so newly created account
+    // vaults remain within Ledger's fifteen-key policy after the NUMS internal key.
+    if (xonlys.length > BTC_VAULT_MAX_PARTICIPANTS) {
+        throw new Error(`too many keys: ${xonlys.length} exceeds the vault participant limit of ${BTC_VAULT_MAX_PARTICIPANTS}`);
+    }
+    const ops = [];
+    xonlys.forEach((pk, i) => {
+        // BIP-342 assigns non-32-byte pushes unknown public-key semantics, so reject
+        // them before they can become an unintended successful CHECKSIGADD.
+        if (pk.length !== 32) {
+            throw new Error(`x-only key #${i} must be 32 bytes, got ${pk.length}`);
+        }
+        ops.push(pk);
+        ops.push(i === 0 ? "CHECKSIG" : "CHECKSIGADD");
+    });
+    ops.push(k);
+    ops.push("NUMEQUAL");
+    return ops;
+}
+/** Serialise the k-of-n ladder to tapscript bytes. */
+export function buildKofNScript(xonlys, k) {
+    return Script.encode(kOfNOps(xonlys, k));
+}

package/dist/btc/vault/spend.d.ts

@@ -0,0 +1,63 @@
+import * as btc from "@scure/btc-signer";
+import type { Leaf } from "./types.ts";
+/**
+ * The unsigned spend of a vault, built once for everyone who signs or
+ * verifies it: the app's signing session (browser and server), the Ledger
+ * PSBT and the SDK's signer. A BIP-341 signature commits to every input's
+ * outpoint, amount, script and sequence, to the outputs and to the version and
+ * lock time, so these parties agree byte for byte or no signature verifies.
+ */
+/** Opt-in RBF on every input. */
+export declare const VAULT_SPEND_SEQUENCE = 4294967293;
+export declare const VAULT_SPEND_VERSION = 2;
+export declare const VAULT_SPEND_LOCKTIME = 0;
+/** A vault UTXO the spend consumes: its id names it in the signing protocol. */
+export type VaultSpendInput = {
+    id: string;
+    txid: string;
+    vout: number;
+    /** Sats. */
+    amount: number | bigint;
+};
+export type VaultSpendOutput = {
+    script: Uint8Array;
+    amount: bigint;
+};
+/**
+ * The inputs in the order every party signs: by utxo id, code point order.
+ * The input index is part of what each signature commits to.
+ */
+export declare function vaultSpendInputOrder<T extends {
+    id: string;
+}>(inputs: readonly T[]): T[];
+/**
+ * `outputs` then the change back to the vault: the inputs less the outputs
+ * less `fee`, when that is positive. Throws when the inputs cannot pay.
+ */
+export declare function withVaultChange(inputs: readonly VaultSpendInput[], outputs: readonly VaultSpendOutput[], vaultScript: Uint8Array, fee: number | bigint): VaultSpendOutput[];
+/**
+ * The unsigned transaction spending vault UTXOs: inputs in
+ * {@link vaultSpendInputOrder}, each with sequence
+ * {@link VAULT_SPEND_SEQUENCE} and its witness UTXO (the vault's script and
+ * the input's amount), then `outputs` in the order given; version
+ * {@link VAULT_SPEND_VERSION}, lock time {@link VAULT_SPEND_LOCKTIME}. With
+ * `leaves`, each input also lists them as its tapleaf scripts (a PSBT's
+ * `tapLeafScript`), which the finalizer and a hardware signer read.
+ *
+ * Returns the inputs in transaction order, so input `i` is `inputs[i]`.
+ */
+export declare function buildVaultSpend<Input extends VaultSpendInput>({ vaultScript, inputs, outputs, leaves, }: {
+    vaultScript: Uint8Array;
+    inputs: readonly Input[];
+    outputs: readonly VaultSpendOutput[];
+    leaves?: readonly Leaf[];
+}): {
+    tx: btc.Transaction;
+    inputs: Input[];
+};
+/**
+ * The BIP-341 script-path sighash (SIGHASH_DEFAULT) a signer of `leafScript`
+ * signs for input `index` of a {@link buildVaultSpend} transaction, every
+ * input's prevout read from its witness UTXO.
+ */
+export declare function vaultSpendSighash(tx: btc.Transaction, index: number, leafScript: Uint8Array): Uint8Array;

package/dist/btc/vault/spend.js

@@ -0,0 +1,93 @@
+import * as btc from "@scure/btc-signer";
+import { TAP_LEAF_VERSION } from "@scure/btc-signer/payment.js";
+import { compareCodepoint } from "./canonical-order.js";
+/**
+ * The unsigned spend of a vault, built once for everyone who signs or
+ * verifies it: the app's signing session (browser and server), the Ledger
+ * PSBT and the SDK's signer. A BIP-341 signature commits to every input's
+ * outpoint, amount, script and sequence, to the outputs and to the version and
+ * lock time, so these parties agree byte for byte or no signature verifies.
+ */
+/** Opt-in RBF on every input. */
+export const VAULT_SPEND_SEQUENCE = 0xff_ff_ff_fd;
+export const VAULT_SPEND_VERSION = 2;
+export const VAULT_SPEND_LOCKTIME = 0;
+/**
+ * The inputs in the order every party signs: by utxo id, code point order.
+ * The input index is part of what each signature commits to.
+ */
+export function vaultSpendInputOrder(inputs) {
+    return [...inputs].sort((a, b) => compareCodepoint(a.id, b.id));
+}
+/**
+ * `outputs` then the change back to the vault: the inputs less the outputs
+ * less `fee`, when that is positive. Throws when the inputs cannot pay.
+ */
+export function withVaultChange(inputs, outputs, vaultScript, fee) {
+    const total = inputs.reduce((sum, input) => sum + BigInt(input.amount), 0n);
+    const spent = outputs.reduce((sum, output) => sum + output.amount, 0n);
+    const change = total - spent - BigInt(fee);
+    if (change < 0n) {
+        throw new Error(`Insufficient funds: have ${total}, need ${spent + BigInt(fee)}`);
+    }
+    return change > 0n
+        ? [...outputs, { script: vaultScript, amount: change }]
+        : [...outputs];
+}
+/**
+ * The unsigned transaction spending vault UTXOs: inputs in
+ * {@link vaultSpendInputOrder}, each with sequence
+ * {@link VAULT_SPEND_SEQUENCE} and its witness UTXO (the vault's script and
+ * the input's amount), then `outputs` in the order given; version
+ * {@link VAULT_SPEND_VERSION}, lock time {@link VAULT_SPEND_LOCKTIME}. With
+ * `leaves`, each input also lists them as its tapleaf scripts (a PSBT's
+ * `tapLeafScript`), which the finalizer and a hardware signer read.
+ *
+ * Returns the inputs in transaction order, so input `i` is `inputs[i]`.
+ */
+export function buildVaultSpend({ vaultScript, inputs, outputs, leaves, }) {
+    const ordered = vaultSpendInputOrder(inputs);
+    const tx = new btc.Transaction({
+        version: VAULT_SPEND_VERSION,
+        lockTime: VAULT_SPEND_LOCKTIME,
+    });
+    for (const input of ordered) {
+        tx.addInput({
+            txid: input.txid,
+            index: input.vout,
+            sequence: VAULT_SPEND_SEQUENCE,
+            witnessUtxo: { script: vaultScript, amount: BigInt(input.amount) },
+            ...(leaves && {
+                tapLeafScript: leaves.map((leaf) => [
+                    {
+                        // A control block's first byte is the leaf version plus the
+                        // output key's parity, which the struct keeps apart.
+                        version: leaf.controlBlockStruct.version + leaf.controlBlockStruct.parity,
+                        internalKey: leaf.controlBlockStruct.internalKey,
+                        merklePath: leaf.controlBlockStruct.merklePath,
+                    },
+                    new Uint8Array([...leaf.script, TAP_LEAF_VERSION]),
+                ]),
+            }),
+        });
+    }
+    for (const output of outputs) {
+        tx.addOutput({ script: output.script, amount: output.amount });
+    }
+    return { tx, inputs: ordered };
+}
+/**
+ * The BIP-341 script-path sighash (SIGHASH_DEFAULT) a signer of `leafScript`
+ * signs for input `index` of a {@link buildVaultSpend} transaction, every
+ * input's prevout read from its witness UTXO.
+ */
+export function vaultSpendSighash(tx, index, leafScript) {
+    const prevouts = Array.from({ length: tx.inputsLength }, (_, i) => {
+        const { witnessUtxo } = tx.getInput(i);
+        if (!witnessUtxo) {
+            throw new Error(`Input ${i} of the spend has no witness UTXO`);
+        }
+        return witnessUtxo;
+    });
+    return tx.preimageWitnessV1(index, prevouts.map(({ script }) => script), btc.SigHash.DEFAULT, prevouts.map(({ amount }) => amount), undefined, leafScript, TAP_LEAF_VERSION);
+}

package/dist/btc/vault/tx-size.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Accurate BTC virtual-size (vbytes) estimation for cofund vault spends.
+ *
+ * The old flat `INPUT_VBYTES = 78` under-counted the real taproot SCRIPT-PATH
+ * witness (a 2-of-2 spend is ~108 vB/input: 2 schnorr sigs + the leaf script +
+ * the control block), so at 1 sat/vB (regtest/devnet) the estimated fee fell
+ * below the node's min-relay floor and broadcasts were rejected. These helpers
+ * size each input from the vault's REAL tapscript leaves instead.
+ *
+ * The sizing is exact for the witness, not an upper bound: a k-of-n leaf is
+ * sized for its k signatures and (n − k) empty slots, which is the only shape
+ * that can spend it. What headroom remains is deliberate and lives elsewhere —
+ * the app's `FEE_SAFETY_MULTIPLIER`, and its choice to price every output as
+ * P2TR even when a recipient is a cheaper type.
+ */
+export declare const TX_OVERHEAD_VBYTES = 11;
+/** vbytes of one output: 8 (value) + 1 (script-length prefix) + script bytes. */
+export declare function outputVbytes(scriptLen: number): number;
+type SizingLeaf = {
+    /** Signers in script order. Each occupies one witness slot, signed or not. */
+    signers: unknown[];
+    /** How many of those slots carry a real signature — the leaf's k. */
+    threshold: number;
+    script: Uint8Array;
+    controlBlockStruct: {
+        merklePath: Uint8Array[];
+    };
+};
+/**
+ * vsize of one taproot SCRIPT-PATH input spending `leaf`.
+ *
+ * The witness always has exactly one slot per signer, of which exactly
+ * `threshold` carry a 64-byte schnorr signature and the rest are EMPTY pushes
+ * costing a single length byte:
+ *
+ *   [ k × 64-byte sig | (n − k) × empty | leaf script | control block ]
+ *
+ * Sizing for k rather than n is not optimistic — k is the only spendable shape.
+ * `orderedSigStackForLeaf` caps non-empty slots at the threshold and blanks any
+ * extra valid signature, and the leaf script ends in `OP_NUMEQUAL k`, which
+ * rejects a sum above k outright. Verified against the on-chain witness of tx
+ * `d512fd27…fc8c` (2-of-5, 172-byte script, depth 0): this predicts 341 witness
+ * bytes and the transaction carries exactly 341.
+ *
+ * `threshold` is clamped into [0, n], so a malformed value can only ever make
+ * this over-count — never under-count into a min-relay rejection.
+ *
+ * For a full-threshold leaf (k === n, e.g. 2-of-2) there are no empty slots and
+ * this is identical to the old all-signers sizing. It is only k < n vaults that
+ * change, where the old estimate carried (n − k) × 16 vB of phantom size per
+ * input — 48 vB/input on a 2-of-5.
+ *
+ * Control block = 1 (parity+version) + 32 (internal key) + 32 × merkle depth.
+ */
+export declare function leafInputVbytes(leaf: SizingLeaf): number;
+/**
+ * Total tx vsize: overhead + inputs (all spending the same vault) + outputs.
+ * `outputScriptLens` lets callers size mixed output types exactly; the common
+ * cofund output is P2TR (34-byte script → 43 vB).
+ */
+export declare function vaultTxVbytes({ inputVbytes, nIn, outputScriptLens, }: {
+    inputVbytes: number;
+    nIn: number;
+    outputScriptLens: number[];
+}): number;
+export {};

package/dist/btc/vault/tx-size.js

@@ -0,0 +1,71 @@
+/**
+ * Accurate BTC virtual-size (vbytes) estimation for cofund vault spends.
+ *
+ * The old flat `INPUT_VBYTES = 78` under-counted the real taproot SCRIPT-PATH
+ * witness (a 2-of-2 spend is ~108 vB/input: 2 schnorr sigs + the leaf script +
+ * the control block), so at 1 sat/vB (regtest/devnet) the estimated fee fell
+ * below the node's min-relay floor and broadcasts were rejected. These helpers
+ * size each input from the vault's REAL tapscript leaves instead.
+ *
+ * The sizing is exact for the witness, not an upper bound: a k-of-n leaf is
+ * sized for its k signatures and (n − k) empty slots, which is the only shape
+ * that can spend it. What headroom remains is deliberate and lives elsewhere —
+ * the app's `FEE_SAFETY_MULTIPLIER`, and its choice to price every output as
+ * P2TR even when a recipient is a cheaper type.
+ */
+// A taproot input's non-witness bytes (counted ×4 in weight): 36-byte outpoint
+// + 1-byte empty scriptSig length + 4-byte sequence.
+const NON_WITNESS_INPUT_VBYTES = 41;
+// version(4) + segwit marker+flag(2 weight units = 0.5 vB) + in/out compactSize
+// (1 each) + locktime(4), rounded up — exact for the small input/output counts
+// cofund produces (well under the 253 threshold where compactSize grows).
+export const TX_OVERHEAD_VBYTES = 11;
+/** vbytes of one output: 8 (value) + 1 (script-length prefix) + script bytes. */
+export function outputVbytes(scriptLen) {
+    return 8 + 1 + scriptLen;
+}
+/**
+ * vsize of one taproot SCRIPT-PATH input spending `leaf`.
+ *
+ * The witness always has exactly one slot per signer, of which exactly
+ * `threshold` carry a 64-byte schnorr signature and the rest are EMPTY pushes
+ * costing a single length byte:
+ *
+ *   [ k × 64-byte sig | (n − k) × empty | leaf script | control block ]
+ *
+ * Sizing for k rather than n is not optimistic — k is the only spendable shape.
+ * `orderedSigStackForLeaf` caps non-empty slots at the threshold and blanks any
+ * extra valid signature, and the leaf script ends in `OP_NUMEQUAL k`, which
+ * rejects a sum above k outright. Verified against the on-chain witness of tx
+ * `d512fd27…fc8c` (2-of-5, 172-byte script, depth 0): this predicts 341 witness
+ * bytes and the transaction carries exactly 341.
+ *
+ * `threshold` is clamped into [0, n], so a malformed value can only ever make
+ * this over-count — never under-count into a min-relay rejection.
+ *
+ * For a full-threshold leaf (k === n, e.g. 2-of-2) there are no empty slots and
+ * this is identical to the old all-signers sizing. It is only k < n vaults that
+ * change, where the old estimate carried (n − k) × 16 vB of phantom size per
+ * input — 48 vB/input on a 2-of-5.
+ *
+ * Control block = 1 (parity+version) + 32 (internal key) + 32 × merkle depth.
+ */
+export function leafInputVbytes(leaf) {
+    const controlBlockLen = 33 + 32 * leaf.controlBlockStruct.merklePath.length;
+    const signed = Math.max(0, Math.min(leaf.threshold, leaf.signers.length));
+    const witnessBytes = 1 + // stack item count
+        signed * (1 + 64) + // a 64-byte sig plus its length prefix
+        (leaf.signers.length - signed) + // empty push: length prefix only
+        (1 + leaf.script.length) + // leaf script
+        (1 + controlBlockLen); // control block
+    return NON_WITNESS_INPUT_VBYTES + Math.ceil(witnessBytes / 4);
+}
+/**
+ * Total tx vsize: overhead + inputs (all spending the same vault) + outputs.
+ * `outputScriptLens` lets callers size mixed output types exactly; the common
+ * cofund output is P2TR (34-byte script → 43 vB).
+ */
+export function vaultTxVbytes({ inputVbytes, nIn, outputScriptLens, }) {
+    const outputs = outputScriptLens.reduce((s, len) => s + outputVbytes(len), 0);
+    return TX_OVERHEAD_VBYTES + nIn * inputVbytes + outputs;
+}

package/dist/btc/vault/types.d.ts

@@ -0,0 +1,49 @@
+export type Role = "admin" | "member";
+export interface User {
+    id: string;
+    role: Role;
+    xonly: Uint8Array;
+    pubCompressed: Uint8Array;
+}
+export type VaultType = "ALL" | "ADMINS_INCLUDED" | "ADMINS_REQUIRED";
+export interface VaultContract {
+    vaultType: VaultType;
+    internalKeyXonly: Uint8Array;
+}
+export interface Leaf {
+    threshold: number;
+    signers: User[];
+    script: Uint8Array;
+    leafHash: Uint8Array;
+    controlBlockStruct: {
+        parity: number;
+        version: number;
+        internalKey: Uint8Array;
+        merklePath: Uint8Array[];
+    };
+}
+export type BuildVaultOptions = {
+    /** Default 2 keeps pre-threshold vaults (contractId without the field)
+     *  re-deriving to the same address. */
+    threshold?: number;
+    /**
+     * Rebuild a vault that ALREADY EXISTS on chain, skipping the leaf-key
+     * uniqueness invariant.
+     *
+     * Only `buildTaprootFromContractId` may set this. A vault created before the
+     * invariant existed may hold a duplicated roster; its address must still
+     * resolve or every read path (balances, deposit address, PDFs, cron, the
+     * sweep that moves the funds to safety) breaks and the coins become
+     * unreachable. Never set it on a creation path — that is the one place the
+     * invariant is load-bearing.
+     */
+    reconstructingExistingVault?: boolean;
+};
+export interface BuiltVault {
+    merkleRoot?: Uint8Array;
+    tweakedPubkey: Uint8Array;
+    scriptPubKey: Uint8Array;
+    address: string;
+    leaves: Leaf[];
+    internalPubKey: Uint8Array;
+}

package/dist/btc/vault/types.js

@@ -0,0 +1 @@
+export {};

package/dist/btc/vault/vault-policy.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Account-Based Vault Builder
+ *
+ * Builds BTC vaults from account-level xpubs. Everything is deterministic:
+ * given xpubs + roles + vaultType + network + NUMS recipe, the vault address
+ * is reproducible.
+ *
+ * Key differences from the legacy MuSig2 builder (build.ts):
+ * - Internal key: unspendable NUMS point (script-path-only, no key-path spend)
+ * - ADMINS_REQUIRED: each admin leaf uses a unique branch namespace
+ *   (leaf i → branch 2*i) so Ledger sees distinct keys per script
+ * - All keys are derived from xpubs at runtime via deriveChildFromXpub
+ */
+/** biome-ignore-all lint/suspicious/noBitwiseOperators: Taproot control-block bytes encode parity with bit masks. */
+import type { BTC_NETWORK } from "@scure/btc-signer/utils.js";
+import { type Bip341NumsRecipe } from "./bip341-nums.ts";
+import { type ParticipantOrdering } from "./participant-order.ts";
+import type { BuiltVault, Leaf, VaultType } from "./types.ts";
+/** Minimal user input — everything else is derived deterministically. */
+export type AccountVaultUser = {
+    id: string;
+    role: "admin" | "member";
+    accountXpub: string;
+};
+export type AccountVaultBuildOptions = {
+    nums: Bip341NumsRecipe;
+    btcNetwork?: BTC_NETWORK;
+    /**
+     * Signatures required to spend. The default preserves addresses for vaults
+     * created before the serialized contract included a threshold.
+     */
+    threshold?: number;
+    /**
+     * Rebuild a vault that ALREADY EXISTS on chain, skipping the leaf-key
+     * uniqueness invariant.
+     *
+     * Only `buildTaprootFromContractId` may set this. A vault created before the
+     * invariant existed may hold a duplicated roster; its address must still
+     * resolve or every read path (balances, deposit address, PDFs, cron, the
+     * sweep that moves the funds to safety) breaks and the coins become
+     * unreachable. Never set it on a creation path — that is the one place the
+     * invariant is load-bearing.
+     */
+    reconstructingExistingVault?: boolean;
+    /**
+     * Which participant-ordering rule to sort the roster under.
+     *
+     * Defaults to {@link ORDERING_ICU_EN_V1} because that is what every vault
+     * created before the rule was recorded used — so a caller that forgets to
+     * pass it reproduces a historical address rather than inventing a new one.
+     * Creation paths must pass {@link CURRENT_PARTICIPANT_ORDERING} explicitly and
+     * persist it in the contract.
+     */
+    participantOrdering?: ParticipantOrdering;
+};
+/**
+ * Sort account vault users deterministically:
+ * admins first, then members. Within each group, sort by accountXpub.
+ *
+ * `ordering` is not optional and must come from the vault's own contract (see
+ * {@link participantOrderingOf}). This order IS part of the vault's address —
+ * it fixes the key order inside the tapscript, and for ADMINS_REQUIRED it fixes
+ * which admin owns which derivation branch — so sorting a roster under the
+ * wrong rule yields a different, unfunded address.
+ */
+export declare function sortAccountUsers(users: AccountVaultUser[], ordering: ParticipantOrdering): AccountVaultUser[];
+/**
+ * Build an account-based vault from xpubs.
+ *
+ * Returns the standard `BuiltVault` so all downstream code
+ * (taprootUtils, getVaultDetails, finalizeTx, cron) works unchanged.
+ *
+ * For ADMINS_REQUIRED vaults, leaf `i` derives keys at branch `2*i`,
+ * producing a unique key namespace per leaf. This satisfies the Ledger
+ * restriction that the same key must not appear in multiple scripts.
+ *
+ * For NAR vaults (ALL / ADMINS_INCLUDED), a single leaf at branch 0.
+ */
+export declare function buildAccountBasedVault(users: AccountVaultUser[], vaultType: VaultType, network: "mainnet" | "testnet", options: AccountVaultBuildOptions): BuiltVault;
+/**
+ * Map each built leaf back to the derivation branch its keys came from.
+ *
+ * The forward assignment lives in `buildAccountBasedVault` above: admin `i`
+ * in *sorted-admin* order owns branch `2*i`, and every signer's key inside
+ * that leaf is derived from that leaf's branch. The inverse is not the array
+ * index — `btc.taprootListToTree` returns leaves in Huffman tree-walk order,
+ * which diverges from creation order at 3 or more leaves. A leaf's branch can
+ * only be recovered from its *contents*, so this matches the leaf's admin key
+ * (script position 0) against each sorted admin's candidate key.
+ *
+ * Every consumer that needs a leaf's branch must go through here: the
+ * software signer's key derivation, and the Ledger PSBT's BIP-371
+ * tap-bip32-derivation records (which are malformed if a key is paired with a
+ * leaf that does not contain it).
+ *
+ * NAR vaults (ALL / ADMINS_INCLUDED) are a single leaf at branch 0.
+ *
+ * `ordering` must be the rule the vault was CREATED under, read off its own
+ * contract. Sorting the admins under a different rule permutes the branch
+ * assignment, so the signer derives a key that is not in the leaf it is paired
+ * with — a malformed PSBT on the Ledger path and a signature that cannot
+ * satisfy the script on the software path.
+ */
+export declare function buildLeafBranchMap(leaves: Leaf[], vaultType: VaultType, accountXpubs: AccountVaultUser[] | undefined, ordering: ParticipantOrdering): Map<Leaf, number>;
+/**
+ * Compute the unspendable internal key x-only for a given network.
+ * Used by the serializer to store a backward-compatible aggregateKey.
+ */
+export declare function getUnspendableInternalKeyXonly(network: "mainnet" | "testnet", numsRecipe: Bip341NumsRecipe): Uint8Array;