@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/btc/vault/vault-policy.js

@@ -0,0 +1,213 @@
+/**
+ * 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 { hex } from "@scure/base";
+import * as btc from "@scure/btc-signer";
+import { taprootTweakPubkey } from "@scure/btc-signer/utils.js";
+import { deriveBip341NumsKey } from "./bip341-nums.js";
+import { buildAdminRequiredThenKofN } from "./build.js";
+import { assertDistinctLeafKeys } from "./helpers.js";
+import { ORDERING_ICU_EN_V1, xpubComparatorFor, } from "./participant-order.js";
+import { buildKofNScript } from "./script.js";
+import { COFUND_LEAF_INDEX, deriveChildFromXpub } from "./xpub.js";
+const COFUND_INDEX = COFUND_LEAF_INDEX;
+// ── Sorting ──────────────────────────────────────────────────────────────
+/**
+ * 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 function sortAccountUsers(users, ordering) {
+    const compareXpub = xpubComparatorFor(ordering);
+    return [...users].sort((a, b) => {
+        if (a.role !== b.role) {
+            return a.role === "admin" ? -1 : 1;
+        }
+        return compareXpub(a.accountXpub, b.accountXpub);
+    });
+}
+// ── Builder ──────────────────────────────────────────────────────────────
+/**
+ * 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 function buildAccountBasedVault(users, vaultType, network, options) {
+    const threshold = options.threshold ?? 2;
+    const sorted = sortAccountUsers(users, options.participantOrdering ?? ORDERING_ICU_EN_V1);
+    const admins = sorted.filter((u) => u.role === "admin");
+    if (threshold < 2 || threshold > sorted.length) {
+        throw new Error(`Invalid threshold ${threshold}: must be between 2 and ${sorted.length}`);
+    }
+    // BIP341 NUMS point adapted to Ledger's xpub-backed wildcard policy. The
+    // public recipe reconstructs the same /0/COFUND_ACCOUNT child everywhere.
+    const { internalXonly: internalKeyXonly } = deriveBip341NumsKey(options.nums, network);
+    const drafts = [];
+    const isNAR = vaultType === "ALL" || vaultType === "ADMINS_INCLUDED";
+    if (isNAR) {
+        // Single leaf, all keys derived at branch 0
+        const leafUsers = sorted.map((u) => {
+            const { compressedPubKey, xonly } = deriveChildFromXpub(u.accountXpub, 0, COFUND_INDEX);
+            return {
+                id: u.id,
+                role: u.role,
+                xonly,
+                pubCompressed: compressedPubKey,
+            };
+        });
+        const allXonly = leafUsers.map((u) => u.xonly);
+        const script = buildKofNScript(allXonly, threshold);
+        drafts.push({ threshold, signers: leafUsers, script });
+    }
+    else {
+        // ADMINS_REQUIRED: one leaf per admin, unique branch per leaf
+        if (admins.length === 0) {
+            throw new Error("ADMINS_REQUIRED vault needs at least one admin");
+        }
+        for (let leafIdx = 0; leafIdx < admins.length; leafIdx++) {
+            const admin = admins[leafIdx];
+            const branch = 2 * leafIdx; // unique namespace per leaf
+            // Derive all users' keys at this leaf's branch
+            const leafUsers = sorted.map((u) => {
+                const { compressedPubKey, xonly } = deriveChildFromXpub(u.accountXpub, branch, COFUND_INDEX);
+                return {
+                    id: u.id,
+                    role: u.role,
+                    xonly,
+                    pubCompressed: compressedPubKey,
+                };
+            });
+            const adminUser = leafUsers.find((u) => u.id === admin.id);
+            const bodyUsers = leafUsers.filter((u) => u.id !== admin.id);
+            const signersInScriptOrder = [adminUser, ...bodyUsers];
+            const allXonly = [adminUser.xonly, ...bodyUsers.map((u) => u.xonly)];
+            const script = buildAdminRequiredThenKofN(adminUser.xonly, allXonly, threshold);
+            drafts.push({ threshold, signers: signersInScriptOrder, script });
+        }
+    }
+    // ── Taproot tree + P2TR ────────────────────────────────────────────
+    // Before the address exists: no leaf may hold one key in two slots.
+    if (!options.reconstructingExistingVault) {
+        assertDistinctLeafKeys(drafts);
+    }
+    const leavesList = drafts.map((d) => ({
+        script: d.script,
+        version: 0xc0,
+    }));
+    const tree = btc.taprootListToTree(leavesList);
+    const res = btc.p2tr(internalKeyXonly, tree, options.btcNetwork, true);
+    // ── Build Leaf[] with control blocks ───────────────────────────────
+    const byScript = new Map(drafts.map((d) => [hex.encode(d.script), d]));
+    const [, parity] = taprootTweakPubkey(internalKeyXonly, res.tapMerkleRoot);
+    const outLeaves = res.leaves.map((leaf) => {
+        const key = hex.encode(leaf.script);
+        const d = byScript.get(key);
+        const tweakedParity = res.tweakedPubkey.length === 33
+            ? res.tweakedPubkey[0] & 1 // 0x02=>0, 0x03=>1
+            : 0;
+        const baseVer = (leaf.version ?? 0xc0) & 0xfe;
+        const cbVersion = baseVer | tweakedParity;
+        return {
+            threshold: d.threshold,
+            signers: d.signers,
+            script: d.script,
+            leafHash: leaf.hash,
+            controlBlockStruct: {
+                version: cbVersion,
+                internalKey: res.tapInternalKey,
+                merklePath: leaf.path,
+                parity,
+            },
+        };
+    });
+    return {
+        merkleRoot: res.tapMerkleRoot,
+        tweakedPubkey: res.tweakedPubkey,
+        scriptPubKey: res.script,
+        address: res.address,
+        leaves: outLeaves,
+        internalPubKey: internalKeyXonly,
+    };
+}
+/**
+ * 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 function buildLeafBranchMap(leaves, vaultType, accountXpubs, ordering) {
+    const map = new Map();
+    if (vaultType === "ALL" || vaultType === "ADMINS_INCLUDED") {
+        for (const leaf of leaves) {
+            map.set(leaf, 0);
+        }
+        return map;
+    }
+    if (!accountXpubs) {
+        return map;
+    }
+    const sortedAdmins = sortAccountUsers(accountXpubs, ordering).filter((u) => u.role === "admin");
+    const branchByAdminKey = new Map();
+    for (let adminIdx = 0; adminIdx < sortedAdmins.length; adminIdx++) {
+        const branch = 2 * adminIdx;
+        const { xonly } = deriveChildFromXpub(sortedAdmins[adminIdx].accountXpub, branch, COFUND_INDEX);
+        branchByAdminKey.set(hex.encode(xonly), branch);
+    }
+    for (const leaf of leaves) {
+        // Leaf signers are built admin-first (`[adminUser, ...bodyUsers]`), and
+        // the script encodes that same admin at position 0.
+        const branch = branchByAdminKey.get(hex.encode(leaf.signers[0].xonly));
+        if (branch !== undefined) {
+            map.set(leaf, branch);
+        }
+    }
+    return map;
+}
+/**
+ * Compute the unspendable internal key x-only for a given network.
+ * Used by the serializer to store a backward-compatible aggregateKey.
+ */
+export function getUnspendableInternalKeyXonly(network, numsRecipe) {
+    return deriveBip341NumsKey(numsRecipe, network).internalXonly;
+}

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

@@ -0,0 +1,80 @@
+import type { Bip341NumsRecipe } from "./bip341-nums.ts";
+import { type ParticipantOrdering } from "./participant-order.ts";
+import type { Role, User, VaultType } from "./types.ts";
+export type VaultContractIdData = {
+    aggregateKey: string;
+    vaultType: VaultType;
+    companyUsers: User[];
+    /** True for account-based vaults (xpub-derived, unspendable internal key) */
+    accountBased?: boolean;
+    /** Network — only present for account-based vaults */
+    network?: "mainnet" | "testnet";
+    /** Account xpubs per user — only present for account-based vaults */
+    accountXpubs?: {
+        id: string;
+        role: Role;
+        accountXpub: string;
+    }[];
+    /** Public proof material for the account vault's BIP341 NUMS key. */
+    nums?: Bip341NumsRecipe;
+    /** Signature threshold; absent on vaults created before it was configurable (= 2) */
+    threshold?: number;
+    /**
+     * Rule the roster was ordered under when the address was derived. Always
+     * resolved (never undefined) on the way out — see {@link participantOrderingOf}.
+     */
+    participantOrdering: ParticipantOrdering;
+};
+/**
+ * Input to the legacy serializer.
+ *
+ * Deliberately NOT {@link VaultContractIdData}: the legacy format stores x-only
+ * keys inline and orders them by `hex(xonly)`, so it has no participant xpub
+ * ordering to record. Lowercase hex sorts identically under every collation,
+ * which is why the legacy format was never exposed to the locale defect that
+ * `participant-order.ts` fixes.
+ */
+type LegacyVaultContractInput = {
+    aggregateKey: string;
+    vaultType: VaultType;
+    companyUsers: User[];
+    threshold?: number;
+};
+/**
+ * Serializes vault contract data for storage in the database (legacy format).
+ */
+export declare function serializeVaultContractData(data: LegacyVaultContractInput): string;
+export type AccountBasedContractData = {
+    accountBased: true;
+    vaultType: VaultType;
+    network: "mainnet" | "testnet";
+    nums: Bip341NumsRecipe;
+    companyUsers: {
+        id: string;
+        role: Role;
+        accountXpub: string;
+    }[];
+    /** Signature threshold; absent on vaults created before it was configurable (= 2) */
+    threshold?: number;
+    /**
+     * Rule the roster is ordered under. Required — the address cannot be
+     * reproduced without it, and omitting it silently means "the historical
+     * `localeCompare` ordering" forever.
+     */
+    participantOrdering: ParticipantOrdering;
+};
+/**
+ * Serializes account-based vault contract data.
+ * Only stores xpubs + roles — everything else is deterministic.
+ *
+ * `companyUsers` is written in the caller's order and re-sorted on every read,
+ * so the stored order is not load-bearing; `participantOrdering` is what fixes
+ * the address.
+ */
+export declare function serializeAccountBasedData(data: AccountBasedContractData): string;
+/**
+ * Deserializes vault contract data from database storage.
+ * Auto-detects legacy vs account-based format.
+ */
+export declare function deserializeVaultContractData(json: string): VaultContractIdData;
+export {};

package/dist/btc/vault/vaultContractUtil.js

@@ -0,0 +1,87 @@
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils";
+import { participantOrderingOf, } from "./participant-order.js";
+import { getUnspendableInternalKeyXonly } from "./vault-policy.js";
+import { COFUND_LEAF_INDEX, deriveChildFromXpub } from "./xpub.js";
+/**
+ * Serializes vault contract data for storage in the database (legacy format).
+ */
+export function serializeVaultContractData(data) {
+    return JSON.stringify({
+        ...data,
+        companyUsers: data.companyUsers.map((u) => ({
+            id: u.id,
+            role: u.role,
+            xonly: bytesToHex(u.xonly),
+        })),
+    });
+}
+/**
+ * Serializes account-based vault contract data.
+ * Only stores xpubs + roles — everything else is deterministic.
+ *
+ * `companyUsers` is written in the caller's order and re-sorted on every read,
+ * so the stored order is not load-bearing; `participantOrdering` is what fixes
+ * the address.
+ */
+export function serializeAccountBasedData(data) {
+    // Validate the complete public NUMS derivation before persisting its recipe.
+    getUnspendableInternalKeyXonly(data.network, data.nums);
+    return JSON.stringify(data);
+}
+// ── Deserializer (auto-detects format) ───────────────────────────────────
+/**
+ * Deserializes vault contract data from database storage.
+ * Auto-detects legacy vs account-based format.
+ */
+export function deserializeVaultContractData(json) {
+    try {
+        const raw = JSON.parse(json);
+        // Account-based format: { accountBased: true, ... }
+        if (raw.accountBased === true) {
+            const { vaultType, network, nums, companyUsers, threshold, participantOrdering, } = raw;
+            const cofundIndex = COFUND_LEAF_INDEX;
+            const users = companyUsers.map((u) => {
+                const { compressedPubKey, xonly } = deriveChildFromXpub(u.accountXpub, 0, cofundIndex);
+                return {
+                    id: u.id,
+                    role: u.role,
+                    xonly,
+                    pubCompressed: compressedPubKey,
+                };
+            });
+            // Unspendable internal key as the "aggregateKey"
+            // Missing or malformed NUMS proof material fails closed here. Old
+            // development account records must be recreated before funding.
+            const internalXonly = getUnspendableInternalKeyXonly(network, nums);
+            return {
+                aggregateKey: bytesToHex(internalXonly),
+                vaultType,
+                companyUsers: users,
+                accountBased: true,
+                network,
+                accountXpubs: companyUsers,
+                nums,
+                threshold,
+                // Absent on every vault created before the rule was recorded, and those
+                // were all ordered by `localeCompare` — so resolve, never default at the
+                // call site.
+                participantOrdering: participantOrderingOf(participantOrdering),
+            };
+        }
+        // Legacy format: { aggregateKey, vaultType, companyUsers: [{ xonly: hex }] }
+        const initialData = raw;
+        return {
+            ...initialData,
+            companyUsers: initialData.companyUsers.map((u) => ({
+                ...u,
+                xonly: hexToBytes(u.xonly),
+            })),
+            // Legacy vaults order by `hex(xonly)`, not by xpub, so this is inert for
+            // them. Set so the field is never undefined on a decoded contract.
+            participantOrdering: participantOrderingOf(undefined),
+        };
+    }
+    catch {
+        throw new Error("Invalid vault contract data JSON");
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * The Cofund leaf's index, `m/86'/coin'/0'/<branch>/<this>`: the key a vault's
+ * taproot leaves are built from and every BTC approval is signed with.
+ */
+export declare const COFUND_LEAF_INDEX = 376864517;
+/** BIP32 version bytes: xprv / xpub on mainnet, tprv / tpub off it. */
+export declare const BIP32_VERSIONS: {
+    readonly mainnet: {
+        readonly private: 76066276;
+        readonly public: 76067358;
+    };
+    readonly testnet: {
+        readonly private: 70615956;
+        readonly public: 70617039;
+    };
+};
+/**
+ * Derive a child public key from an account-level xpub at a given
+ * branch/index (default /0/0).
+ *
+ * Mirrors the ledger-test-app's `derivePubkeysFromXpub`.
+ */
+export declare function deriveChildFromXpub(accountXpub: string, branch?: number, index?: number): {
+    compressedPubKey: Uint8Array;
+    xonly: Uint8Array;
+};
+/** The Cofund leaf's compressed public key, hex, of an account xpub (tpub off mainnet). */
+export declare function btcCofundLeafKey(xpub: string): string;

package/dist/btc/vault/xpub.js

@@ -0,0 +1,41 @@
+import { bytesToHex } from "@noble/hashes/utils";
+import { HDKey } from "@scure/bip32";
+/**
+ * The Cofund leaf's index, `m/86'/coin'/0'/<branch>/<this>`: the key a vault's
+ * taproot leaves are built from and every BTC approval is signed with.
+ */
+export const COFUND_LEAF_INDEX = 376_864_517;
+/** BIP32 version bytes: xprv / xpub on mainnet, tprv / tpub off it. */
+export const BIP32_VERSIONS = {
+    mainnet: { private: 0x04_88_ad_e4, public: 0x04_88_b2_1e },
+    testnet: { private: 0x04_35_83_94, public: 0x04_35_87_cf },
+};
+/**
+ * Derive a child public key from an account-level xpub at a given
+ * branch/index (default /0/0).
+ *
+ * Mirrors the ledger-test-app's `derivePubkeysFromXpub`.
+ */
+export function deriveChildFromXpub(accountXpub, branch = 0, index = 0) {
+    const versions = BIP32_VERSIONS[accountXpub.startsWith("tpub") ? "testnet" : "mainnet"];
+    const account = HDKey.fromExtendedKey(accountXpub, versions);
+    const derived = account.deriveChild(branch).deriveChild(index);
+    if (!derived.publicKey) {
+        throw new Error("Failed to derive public key from xpub");
+    }
+    return {
+        compressedPubKey: derived.publicKey, // 33 bytes (02/03 + x)
+        xonly: derived.publicKey.slice(1), // 32 bytes (x-only / BIP-340)
+    };
+}
+/** The Cofund leaf's compressed public key, hex, of an account xpub (tpub off mainnet). */
+export function btcCofundLeafKey(xpub) {
+    const versions = BIP32_VERSIONS[xpub.startsWith("xpub") ? "mainnet" : "testnet"];
+    const leaf = HDKey.fromExtendedKey(xpub, versions)
+        .deriveChild(0)
+        .deriveChild(COFUND_LEAF_INDEX);
+    if (!leaf.publicKey) {
+        throw new Error("Could not derive the Cofund leaf of a BTC key");
+    }
+    return bytesToHex(leaf.publicKey);
+}

package/dist/btc/witness.d.ts

@@ -0,0 +1,101 @@
+/** biome-ignore-all lint/suspicious/noBitwiseOperators: a control block's first byte is the leaf version plus the output key's parity. */
+import * as btc from "@scure/btc-signer";
+import type { Leaf, User, VaultType } from "./vault/types.ts";
+/**
+ * A vault spend's witness, assembled from the signatures collected for it:
+ * the script-path witness `[signatures… | leaf script | control block]` once
+ * one leaf has its threshold on every input. The app's finalizer (over its
+ * stored partials) and `finalizePsbt` (over a PSBT's `tapScriptSig`s) both
+ * assemble through here.
+ *
+ * Every count is read off the tapscript itself, never the leaf's metadata,
+ * and counts distinct keys: BIP-342 counts a repeated key twice, so a vault
+ * built before the leaf-key uniqueness invariant could otherwise meet its
+ * threshold with one signature.
+ */
+/** Verified signatures over a spend: leaf hash (hex) → input index → signer id → BIP-340 signature. */
+export type SpendPartials = Map<string, Map<number, Map<string, Uint8Array>>>;
+/** A spend being finalized: the unsigned transaction (`buildVaultSpend`), the vault's leaves and the signatures collected. */
+export type WitnessSpend = {
+    tx: btc.Transaction;
+    candidates: Leaf[];
+    partials: SpendPartials;
+};
+/** The finalizer's scope: one leaf, and the signers whose signatures it may use. */
+export type FinalizationPlan = {
+    leafHash: string;
+    approverIds: readonly string[];
+};
+/** The control block of a leaf: its version plus the output key's parity, the internal key, and the merkle path. */
+export declare function encodeCBFromStruct(cbStruct: {
+    version: number;
+    internalKey: Uint8Array;
+    merklePath: Uint8Array[];
+    parity?: number;
+}): Uint8Array;
+/**
+ * Does `sig` verify as `signerXonly`'s BIP340 signature over `msg`?
+ *
+ * The single answer to "did this key actually approve THIS exact transaction".
+ * Malformed input makes noble throw, which is easy to swallow by accident —
+ * always returning a boolean makes it hard for a call site to treat an
+ * unverifiable signature as an approval.
+ */
+export declare function verifyPartialSignatureAgainstMsg(msg: Uint8Array, signerXonly: Uint8Array, sig: Uint8Array): boolean;
+export type LeafScriptPolicy = {
+    kind: "non-admin-required";
+    signatureKeys: Uint8Array[];
+    threshold: number;
+} | {
+    kind: "admin-required";
+    signatureKeys: Uint8Array[];
+    threshold: number;
+    adminKey: Uint8Array;
+    bodyKeys: Uint8Array[];
+    bodyThreshold: number;
+};
+/**
+ * Decode the policy Bitcoin actually executes, rather than trusting metadata.
+ *
+ * The hard threshold is committed by the tapscript. `Leaf.threshold` is useful
+ * descriptive metadata, but it must never be the authority used to decide how
+ * many signatures enter a witness.
+ */
+export declare function leafScriptPolicy(leaf: Leaf): LeafScriptPolicy | null;
+/** Match each script key to one leaf signer slot, preserving duplicate slots. */
+export declare function signerSlotsForScript(leaf: Leaf, signatureKeys: Uint8Array[]): Array<User | undefined>;
+export declare function signatureSlotCountForLeaf(leaf: Leaf): number | null;
+export declare function orderedSigStackForLeaf(spend: {
+    tx: btc.Transaction;
+}, leaf: Leaf, inputIndex: number, bucket: Map<string, Uint8Array>): {
+    stack: Uint8Array[];
+    nonEmpty: number;
+};
+export declare function sigStackSolvesLeaf(spend: {
+    tx: btc.Transaction;
+}, leaf: Leaf, sigStack: Uint8Array[], inputIndex: number): boolean;
+/** An ADMINS_REQUIRED leaf: its admin, then its body signers in script order, and the body's k. */
+export declare function decodeAdminRequiredLeaf(leaf: Leaf): {
+    adminId: string;
+    adminKey: Uint8Array;
+    bodyOrderIds: string[];
+    bodyKeys: Uint8Array[];
+    k: number;
+} | null;
+/**
+ * Select the exact hard-threshold signer identities available for one leaf.
+ * Returns null when the eligible set cannot satisfy the on-chain script.
+ */
+export declare function selectHardThresholdSignerIds(leaf: Leaf, vaultType: VaultType, eligibleSignerIds: ReadonlySet<string>): string[] | null;
+/** Write `leaf`'s witness for input `inputIndex`: the signature stack, the leaf script and its control block. */
+export declare function finalizeWithWitness(tx: btc.Transaction, inputIndex: number, leaf: Leaf, sigStack: Uint8Array[]): Uint8Array<ArrayBufferLike>[];
+/**
+ * Finalize every input with the first candidate leaf that the collected
+ * signatures solve on every input — the template's rules: k of the leaf's
+ * keys, and on an ADMINS_REQUIRED leaf its admin plus k − 1 of the rest.
+ * With a plan, only its leaf and its approvers' signatures count.
+ */
+export declare function tryFinalizeAny(spend: WitnessSpend, vaultType: VaultType, plan?: FinalizationPlan): {
+    finalized: boolean;
+    usedLeaf?: Leaf;
+};