@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/btc/spend.d.ts

@@ -0,0 +1,136 @@
+import type { BtcLeafKeySigner, BtcNetwork } from "../keys/keys.ts";
+import type { BtcPartial, BtcVaultDefinition } from "./types.ts";
+import { type Leaf, type VaultSpendInput } from "./vault/index.ts";
+/**
+ * A Bitcoin transfer signed with nothing the server states taken on trust.
+ *
+ * The vault comes first (`verifyBtcVault`): its taproot tree is rebuilt from
+ * its definition with the app's own builder (`./vault`) and must
+ * derive the vault's address; the signer's leaves and their derivation
+ * branches are read off that tree. Then the spend (`checkBtcSpend`):
+ *
+ * - the transaction is rebuilt here, with the builder the app and the Ledger
+ *   path use (`buildVaultSpend`), with the vault's script and the stated
+ *   amount as every input's prevout, which BIP-341 commits to: an input that
+ *   is not the vault's, or a false amount, makes every signature over it
+ *   invalid; no input appears twice;
+ * - the first output pays the request's recipient its amount; then at most a
+ *   Cofund fee within `maxFeeBps` of the amount, and change back to the vault;
+ * - the network fee (inputs less outputs) is the request's and at most
+ *   `maxFeeRate` sat/vB of the transaction's size as the app prices it: every
+ *   input witnessed by the vault's largest leaf.
+ */
+/** Ceilings on what a spend may cost beyond the transfer itself. */
+export type BtcSpendLimits = {
+    /** The Cofund fee's ceiling, in bps of the amount (default 100). */
+    maxFeeBps?: number;
+    /** The network fee's ceiling, in sat/vB (default 1000). */
+    maxFeeRate?: number;
+};
+/** A Bitcoin vault to verify: its address and the definition it claims; `id` names it. */
+export type BtcVault = {
+    id: string;
+    address: string;
+    definition: BtcVaultDefinition;
+};
+/**
+ * A transfer out of a vault: what it pays, and the spend that carries it.
+ * Every input is the vault's; a signer signs it as the vault's script
+ * spending them.
+ */
+export type BtcTransfer = {
+    vault: {
+        id: string;
+        address: string;
+    };
+    recipient: string;
+    /** Sats. */
+    amount: string;
+    /** Sats: the inputs less the outputs. */
+    networkFee: string;
+    spend: {
+        /** The vault's UTXOs, by id. */
+        inputs: {
+            utxoId: string;
+            txid: string;
+            vout: number;
+            amount: string;
+        }[];
+        /** The recipient, then the Cofund fee if any, then change back to the vault if any. */
+        outputs: {
+            address: string;
+            amount: string;
+        }[];
+    };
+};
+/** A vault whose definition derives its address: its tree, and each leaf's derivation branch. */
+export type VerifiedBtcVault = {
+    id: string;
+    address: string;
+    definition: BtcVaultDefinition;
+    /** sha256 of the definition as the app serializes it: what a keystore pins (`BtcVaultPin`). */
+    definitionHash: string;
+    script: Uint8Array;
+    leaves: {
+        leaf: Leaf;
+        branch: number;
+    }[];
+};
+/** What a checked spend pays, and the vault it spends, for a person or a hook to decide on. */
+export type BtcSpendSummary = {
+    vault: {
+        address: string;
+        vaultType: BtcVaultDefinition["vaultType"];
+        threshold: number;
+        members: {
+            id: string;
+            role: "admin" | "member";
+        }[];
+    };
+    recipient: string;
+    amount: string;
+    /** The Cofund fee output, when the spend carries one. */
+    cofundFee: {
+        address: string;
+        amount: string;
+    } | null;
+    /** Change back to the vault, in sats. */
+    change: string;
+    networkFee: string;
+    inputs: number;
+};
+/** A spend that passed every check, ready to sign. */
+export type CheckedBtcSpend = {
+    vaultScript: Uint8Array;
+    /** In the order signed (`vaultSpendInputOrder`). */
+    inputs: (VaultSpendInput & {
+        amount: bigint;
+    })[];
+    outputs: {
+        script: Uint8Array;
+        amount: bigint;
+    }[];
+    /** The signer's leaves in the verified tree. */
+    leaves: {
+        leaf: Leaf;
+        branch: number;
+    }[];
+    summary: BtcSpendSummary;
+};
+/**
+ * The vault, verified: its definition rebuilt into the taproot tree with the
+ * app's builder, which must derive the vault's address. Keep it for the
+ * vault's next transfer: a definition never changes.
+ */
+export declare function verifyBtcVault(vault: BtcVault, network: BtcNetwork): VerifiedBtcVault;
+/**
+ * Check a BTC transfer's spend of a verified vault for `signer` (see the
+ * module comment). Throws on the first thing that does not hold.
+ */
+export declare function checkBtcSpend(request: BtcTransfer, vault: VerifiedBtcVault, signer: BtcLeafKeySigner, limits?: BtcSpendLimits): CheckedBtcSpend;
+/**
+ * The signer's partials over a checked spend: one BIP-340 signature per input
+ * per leaf, over the BIP-341 sighash (SIGHASH_DEFAULT, `vaultSpendSighash`)
+ * of the transaction `buildVaultSpend` rebuilds.
+ */
+export declare function signBtcSpend(checked: CheckedBtcSpend, signer: BtcLeafKeySigner): BtcPartial[];

package/dist/btc/spend.js

@@ -0,0 +1,180 @@
+import { sha256 } from "@noble/hashes/sha2";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+import { equalBytes } from "@scure/btc-signer/utils.js";
+import { DEFAULT_MAX_FEE_RATE, networkOfAddress, scriptOf, spendVbytes, } from "./spend-rules.js";
+import { buildLeafBranchMap, buildTaprootForNetwork, buildVaultSpend, serializeAccountBasedData, vaultSpendInputOrder, vaultSpendSighash, } from "./vault/index.js";
+const DEFAULT_MAX_FEE_BPS = 100;
+/** The vault's network, from its address; it must be the signer's. */
+function networkOf(vaultAddress, network) {
+    const net = networkOfAddress(vaultAddress);
+    if (!net || (net.bech32 === "bc") !== (network === "mainnet")) {
+        throw new Error(`The vault ${vaultAddress} is not on the signer's network (${network})`);
+    }
+    return net;
+}
+/**
+ * The vault, verified: its definition rebuilt into the taproot tree with the
+ * app's builder, which must derive the vault's address. Keep it for the
+ * vault's next transfer: a definition never changes.
+ */
+export function verifyBtcVault(vault, network) {
+    const { definition } = vault;
+    const net = networkOf(vault.address, network);
+    if ((definition.network === "mainnet") !== (network === "mainnet")) {
+        throw new Error(`Vault ${vault.id}'s definition is for ${definition.network}`);
+    }
+    const { members, ...rest } = definition;
+    const serialized = serializeAccountBasedData({
+        accountBased: true,
+        ...rest,
+        companyUsers: members,
+    });
+    const built = buildTaprootForNetwork(serialized, net);
+    if (built.address !== vault.address) {
+        throw new Error(`Vault ${vault.id}'s definition derives ${built.address}, not its address ${vault.address}`);
+    }
+    const branches = buildLeafBranchMap(built.leaves, definition.vaultType, members, definition.participantOrdering);
+    return {
+        id: vault.id,
+        address: vault.address,
+        definition,
+        definitionHash: bytesToHex(sha256(utf8ToBytes(serialized))),
+        script: built.scriptPubKey,
+        leaves: built.leaves.flatMap((leaf) => {
+            const branch = branches.get(leaf);
+            return branch === undefined ? [] : [{ leaf, branch }];
+        }),
+    };
+}
+/** The inputs in the order every party signs (`vaultSpendInputOrder`). */
+function checkInputs(request) {
+    const { inputs } = request.spend;
+    const seen = new Set();
+    for (const input of inputs) {
+        for (const key of [input.utxoId, `${input.txid}:${input.vout}`]) {
+            if (seen.has(key)) {
+                throw new Error(`The spend lists ${key} twice`);
+            }
+            seen.add(key);
+        }
+    }
+    return vaultSpendInputOrder(inputs.map(({ utxoId, txid, vout, amount }) => ({
+        id: utxoId,
+        txid,
+        vout,
+        amount: BigInt(amount),
+    })));
+}
+/** The Cofund fee's ceiling: `bps` of the amount, rounded up. */
+const feeCeiling = (amount, bps) => (amount * BigInt(bps) + 9999n) / 10000n;
+/** Recipient first, then at most a Cofund fee, then at most change to the vault. */
+function checkOutputs(request, net, vaultScript, maxFeeBps) {
+    const [recipient, ...rest] = request.spend.outputs;
+    if (recipient?.address !== request.recipient ||
+        recipient.amount !== request.amount) {
+        throw new Error(`The spend's first output is not ${request.amount} sats to ${request.recipient}`);
+    }
+    const outputs = [
+        {
+            script: scriptOf(net, recipient.address),
+            amount: BigInt(recipient.amount),
+        },
+    ];
+    let cofundFee = null;
+    let change = null;
+    for (const output of rest) {
+        const script = scriptOf(net, output.address);
+        const amount = BigInt(output.amount);
+        if (change !== null) {
+            throw new Error(`Unexpected output after the change: ${output.address}`);
+        }
+        if (equalBytes(script, vaultScript)) {
+            change = amount;
+        }
+        else if (cofundFee === null) {
+            if (amount > feeCeiling(BigInt(request.amount), maxFeeBps)) {
+                throw new Error(`The Cofund fee of ${amount} sats is over ${maxFeeBps} bps of the amount`);
+            }
+            cofundFee = { address: output.address, amount: output.amount };
+        }
+        else {
+            throw new Error(`Unexpected output: ${amount} sats to ${output.address}`);
+        }
+        outputs.push({ script, amount });
+    }
+    return { outputs, cofundFee, change: change ?? 0n };
+}
+/** The signer's leaves: those of the verified tree that hold its key at their branch. */
+function signerLeaves(vault, signer) {
+    const mine = vault.leaves.filter(({ leaf, branch }) => {
+        const own = signer.leafKey(branch);
+        return leaf.signers.some((member) => equalBytes(member.xonly, own));
+    });
+    if (mine.length === 0) {
+        throw new Error(`Vault ${vault.address} holds no leaf with the signer's key`);
+    }
+    return mine;
+}
+/**
+ * Check a BTC transfer's spend of a verified vault for `signer` (see the
+ * module comment). Throws on the first thing that does not hold.
+ */
+export function checkBtcSpend(request, vault, signer, limits = {}) {
+    if (request.vault.id !== vault.id ||
+        request.vault.address !== vault.address) {
+        throw new Error(`The transfer spends ${request.vault.address}, not the verified vault ${vault.address}`);
+    }
+    const maxFeeBps = limits.maxFeeBps ?? DEFAULT_MAX_FEE_BPS;
+    const maxFeeRate = limits.maxFeeRate ?? DEFAULT_MAX_FEE_RATE;
+    const net = networkOf(vault.address, signer.network);
+    const inputs = checkInputs(request);
+    const { outputs, cofundFee, change } = checkOutputs(request, net, vault.script, maxFeeBps);
+    const leaves = signerLeaves(vault, signer);
+    const fee = inputs.reduce((sum, { amount }) => sum + amount, 0n) -
+        outputs.reduce((sum, { amount }) => sum + amount, 0n);
+    if (fee !== BigInt(request.networkFee)) {
+        throw new Error(`Inputs less outputs is ${fee} sats, not the transfer's network fee of ${request.networkFee}`);
+    }
+    const vsize = spendVbytes(vault, inputs.length, outputs);
+    if (fee > BigInt(maxFeeRate * vsize)) {
+        throw new Error(`The network fee of ${fee} sats is over ${maxFeeRate} sat/vB of ${vsize} vB`);
+    }
+    const { definition } = vault;
+    return {
+        vaultScript: vault.script,
+        inputs,
+        outputs,
+        leaves,
+        summary: {
+            vault: {
+                address: vault.address,
+                vaultType: definition.vaultType,
+                threshold: definition.threshold,
+                members: definition.members.map(({ id, role }) => ({ id, role })),
+            },
+            recipient: request.recipient,
+            amount: request.amount,
+            cofundFee,
+            change: change.toString(),
+            networkFee: fee.toString(),
+            inputs: inputs.length,
+        },
+    };
+}
+/**
+ * The signer's partials over a checked spend: one BIP-340 signature per input
+ * per leaf, over the BIP-341 sighash (SIGHASH_DEFAULT, `vaultSpendSighash`)
+ * of the transaction `buildVaultSpend` rebuilds.
+ */
+export function signBtcSpend(checked, signer) {
+    const { tx, inputs } = buildVaultSpend({
+        vaultScript: checked.vaultScript,
+        inputs: checked.inputs,
+        outputs: checked.outputs,
+    });
+    return checked.leaves.flatMap(({ leaf, branch }) => inputs.map((input, index) => ({
+        utxoId: input.id,
+        leafHash: bytesToHex(leaf.leafHash),
+        signature: bytesToHex(signer.signDigest(branch, vaultSpendSighash(tx, index, leaf.script))),
+    })));
+}

package/dist/btc/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * What the protocol's Bitcoin values look like, as zod schemas: a vault's
+ * definition and a signer's partials over a spend. Every type is inferred
+ * from them.
+ */
+import { z } from "zod";
+/** Every id: cofund, user, policy, vault, request, and a signed `authId`, `callerId` or `userId`. */
+export declare const Uuid: z.ZodUUID;
+/** A 64-byte BIP-340 signature, bare hex. */
+export declare const SchnorrSignature: z.ZodString;
+/** A BIP-86 account key: an xpub, or a tpub off mainnet. */
+export declare const BtcXpub: z.ZodString;
+/** A tapleaf hash: 32 bytes, bare hex. */
+export declare const TapLeafHash: z.ZodString;
+/** A Bitcoin vault's template: everyone equal, admins among the members, or an admin on every spend. */
+export declare const BtcVaultTypeSchema: z.ZodEnum<{
+    ALL: "ALL";
+    ADMINS_INCLUDED: "ADMINS_INCLUDED";
+    ADMINS_REQUIRED: "ADMINS_REQUIRED";
+}>;
+export type BtcVaultType = z.infer<typeof BtcVaultTypeSchema>;
+/**
+ * What a Bitcoin vault's address commits to, as the app stores it: the
+ * template, the threshold, the rule its members are ordered under, the NUMS
+ * recipe of its internal key, and each member's account xpub. `verifyBtcVault`
+ * rebuilds the taproot tree from it with the vault builder (`./vault`) and
+ * checks the address.
+ */
+export declare const BtcVaultDefinitionSchema: z.ZodObject<{
+    vaultType: z.ZodEnum<{
+        ALL: "ALL";
+        ADMINS_INCLUDED: "ADMINS_INCLUDED";
+        ADMINS_REQUIRED: "ADMINS_REQUIRED";
+    }>;
+    network: z.ZodEnum<{
+        testnet: "testnet";
+        mainnet: "mainnet";
+    }>;
+    threshold: z.ZodNumber;
+    participantOrdering: z.ZodEnum<{
+        "icu-en-v1": "icu-en-v1";
+        "role-then-xpub-codepoint-v2": "role-then-xpub-codepoint-v2";
+    }>;
+    nums: z.ZodObject<{
+        scheme: z.ZodLiteral<"bip341-h-plus-r-bip32-public">;
+        version: z.ZodLiteral<1>;
+        r: z.ZodString;
+    }, z.core.$strip>;
+    members: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        role: z.ZodEnum<{
+            admin: "admin";
+            member: "member";
+        }>;
+        accountXpub: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BtcVaultDefinition = z.infer<typeof BtcVaultDefinitionSchema>;
+/** One BIP-340 signature by the caller's key in `leafHash`, over the spend's input `utxoId`. */
+export declare const BtcPartialSchema: z.ZodObject<{
+    utxoId: z.ZodUUID;
+    leafHash: z.ZodString;
+    signature: z.ZodString;
+}, z.core.$strip>;
+export type BtcPartial = z.infer<typeof BtcPartialSchema>;

package/dist/btc/types.js

@@ -0,0 +1,62 @@
+/**
+ * What the protocol's Bitcoin values look like, as zod schemas: a vault's
+ * definition and a signer's partials over a spend. Every type is inferred
+ * from them.
+ */
+import { z } from "zod";
+import { BIP341_NUMS_RECIPE_VERSION, BIP341_NUMS_SCHEME, } from "./vault/bip341-nums.js";
+import { BTC_VAULT_MAX_PARTICIPANTS } from "./vault/limits.js";
+import { ORDERING_ICU_EN_V1, ORDERING_XPUB_CODEPOINT_V2, } from "./vault/participant-order.js";
+/** Every id: cofund, user, policy, vault, request, and a signed `authId`, `callerId` or `userId`. */
+export const Uuid = z.uuid();
+/** A 64-byte BIP-340 signature, bare hex. */
+export const SchnorrSignature = z
+    .string()
+    .regex(/^[0-9a-fA-F]{128}$/, "a 64-byte BIP-340 signature");
+/** A BIP-86 account key: an xpub, or a tpub off mainnet. */
+export const BtcXpub = z
+    .string()
+    .regex(/^[xt]pub[1-9A-HJ-NP-Za-km-z]{107}$/, "an xpub or tpub");
+/** A tapleaf hash: 32 bytes, bare hex. */
+export const TapLeafHash = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/, "a 32-byte tapleaf hash");
+/** A Bitcoin vault's template: everyone equal, admins among the members, or an admin on every spend. */
+export const BtcVaultTypeSchema = z.enum([
+    "ALL",
+    "ADMINS_INCLUDED",
+    "ADMINS_REQUIRED",
+]);
+/**
+ * What a Bitcoin vault's address commits to, as the app stores it: the
+ * template, the threshold, the rule its members are ordered under, the NUMS
+ * recipe of its internal key, and each member's account xpub. `verifyBtcVault`
+ * rebuilds the taproot tree from it with the vault builder (`./vault`) and
+ * checks the address.
+ */
+export const BtcVaultDefinitionSchema = z.object({
+    vaultType: BtcVaultTypeSchema,
+    network: z.enum(["mainnet", "testnet"]),
+    /** Signatures the script requires (2 on a vault from before it was configurable). */
+    threshold: z.number().int().min(1).max(BTC_VAULT_MAX_PARTICIPANTS),
+    participantOrdering: z.enum([ORDERING_ICU_EN_V1, ORDERING_XPUB_CODEPOINT_V2]),
+    nums: z.object({
+        scheme: z.literal(BIP341_NUMS_SCHEME),
+        version: z.literal(BIP341_NUMS_RECIPE_VERSION),
+        r: z.string().regex(/^[0-9a-f]{64}$/, "32 bytes of hex"),
+    }),
+    members: z
+        .array(z.object({
+        id: Uuid,
+        role: z.enum(["admin", "member"]),
+        accountXpub: BtcXpub,
+    }))
+        .min(1)
+        .max(BTC_VAULT_MAX_PARTICIPANTS),
+});
+/** One BIP-340 signature by the caller's key in `leafHash`, over the spend's input `utxoId`. */
+export const BtcPartialSchema = z.object({
+    utxoId: Uuid,
+    leafHash: TapLeafHash,
+    signature: SchnorrSignature,
+});

package/dist/btc/vault/bip341-nums.d.ts

@@ -0,0 +1,35 @@
+export declare const BIP341_NUMS_RECIPE_VERSION: 1;
+export declare const BIP341_NUMS_SCHEME: "bip341-h-plus-r-bip32-public";
+export declare const BIP341_NUMS_CHILD_INDEX: 376864517;
+/**
+ * Public proof material for Cofund's BIP341 NUMS internal-key construction.
+ *
+ * `r` is intentionally public. It proves that the synthetic extended
+ * public key was constructed from BIP341's standard NUMS point rather than
+ * from a public key whose discrete logarithm is known.
+ */
+export type Bip341NumsRecipe = {
+    scheme: typeof BIP341_NUMS_SCHEME;
+    version: typeof BIP341_NUMS_RECIPE_VERSION;
+    r: string;
+};
+export type DerivedBip341NumsKey = {
+    rootCompressed: Uint8Array;
+    chainCode: Uint8Array;
+    extendedPublicKey: string;
+    internalCompressed: Uint8Array;
+    internalXonly: Uint8Array;
+};
+export type RandomBytesSource = (length: number) => Uint8Array;
+/** Generate fresh, public proof material once during vault creation. */
+export declare function createBip341NumsRecipe(randomSource?: RandomBytesSource): Bip341NumsRecipe;
+/**
+ * Reconstruct the public-only extended key used by software and Ledger.
+ *
+ * Ledger wallet policies currently require an xpub-backed key placeholder and
+ * a receive/change derivation suffix. The root point is `H + rG`, where `H` is
+ * BIP341's standard NUMS point and `r` is the recipe's public scalar. BIP32
+ * public derivation adds only publicly computable point tweaks, so no private
+ * key is known unless the discrete logarithm of `H` is known.
+ */
+export declare function deriveBip341NumsKey(recipe: Bip341NumsRecipe, network: "mainnet" | "testnet"): DerivedBip341NumsKey;

package/dist/btc/vault/bip341-nums.js

@@ -0,0 +1,121 @@
+import { schnorr, secp256k1 } from "@noble/curves/secp256k1.js";
+import { bytesToNumberBE } from "@noble/curves/utils.js";
+import { bytesToHex, hexToBytes, randomBytes } from "@noble/hashes/utils";
+import { HDKey } from "@scure/bip32";
+export const BIP341_NUMS_RECIPE_VERSION = 1;
+export const BIP341_NUMS_SCHEME = "bip341-h-plus-r-bip32-public";
+export const BIP341_NUMS_CHILD_INDEX = 376_864_517;
+const BIP341_NUMS_H_X = "50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0";
+const NUMS_CHAIN_CODE_TAG = "Cofund/NUMSXpubChainCode/v1";
+const NUMS_BRANCH = 0;
+const SCALAR_HEX = /^[0-9a-f]{64}$/;
+const CURVE_ORDER = secp256k1.Point.CURVE().n;
+const TESTNET_HD_VERSIONS = {
+    public: 0x04_35_87_cf,
+    private: 0x04_35_83_94,
+};
+const HD_VERSIONS = {
+    mainnet: {
+        public: 0x04_88_b2_1e,
+        private: 0x04_88_ad_e4,
+    },
+    testnet: TESTNET_HD_VERSIONS,
+};
+class NonExactBip32DerivationError extends Error {
+}
+/** Generate fresh, public proof material once during vault creation. */
+export function createBip341NumsRecipe(randomSource = randomBytes) {
+    // Rejection sampling gives BIP341's exact uniform distribution over 0..n-1
+    // recommended by BIP341, without reducing random bytes modulo the order.
+    for (let attempt = 0; attempt < 128; attempt++) {
+        const candidate = randomSource(32);
+        if (candidate.length !== 32) {
+            throw new Error("BIP341 NUMS random source must return 32 bytes");
+        }
+        if (bytesToNumberBE(candidate) < CURVE_ORDER) {
+            const recipe = {
+                scheme: BIP341_NUMS_SCHEME,
+                version: BIP341_NUMS_RECIPE_VERSION,
+                r: bytesToHex(candidate),
+            };
+            try {
+                deriveBip341NumsKey(recipe, "mainnet");
+                return recipe;
+            }
+            catch (error) {
+                if (error instanceof NonExactBip32DerivationError) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    throw new Error("Unable to sample a valid BIP341 NUMS scalar");
+}
+/** Validate and decode the public scalar committed by a NUMS recipe. */
+function decodeNumsScalar(recipe) {
+    if (recipe.scheme !== BIP341_NUMS_SCHEME) {
+        throw new Error(`Unsupported BIP341 NUMS scheme: ${recipe.scheme}`);
+    }
+    if (recipe.version !== BIP341_NUMS_RECIPE_VERSION) {
+        throw new Error(`Unsupported BIP341 NUMS recipe: ${recipe.version}`);
+    }
+    if (!SCALAR_HEX.test(recipe.r)) {
+        throw new Error("BIP341 NUMS r must be 32-byte lowercase hex");
+    }
+    const scalar = hexToBytes(recipe.r);
+    if (bytesToNumberBE(scalar) >= CURVE_ORDER) {
+        throw new Error("BIP341 NUMS r must be a scalar in 0..n-1");
+    }
+    return scalar;
+}
+/**
+ * Reconstruct the public-only extended key used by software and Ledger.
+ *
+ * Ledger wallet policies currently require an xpub-backed key placeholder and
+ * a receive/change derivation suffix. The root point is `H + rG`, where `H` is
+ * BIP341's standard NUMS point and `r` is the recipe's public scalar. BIP32
+ * public derivation adds only publicly computable point tweaks, so no private
+ * key is known unless the discrete logarithm of `H` is known.
+ */
+export function deriveBip341NumsKey(recipe, network) {
+    const rBytes = decodeNumsScalar(recipe);
+    const h = schnorr.utils.lift_x(bytesToNumberBE(hexToBytes(BIP341_NUMS_H_X)));
+    const r = bytesToNumberBE(rBytes);
+    const rootPoint = r === 0n ? h : h.add(secp256k1.Point.BASE.multiply(r));
+    if (rootPoint.is0()) {
+        throw new NonExactBip32DerivationError("BIP341 NUMS root is the point at infinity");
+    }
+    const rootCompressed = rootPoint.toBytes(true);
+    const chainCode = schnorr.utils.taggedHash(NUMS_CHAIN_CODE_TAG, rootCompressed);
+    const root = new HDKey({
+        versions: HD_VERSIONS[network],
+        publicKey: rootCompressed,
+        chainCode,
+    });
+    if (root.privateKey !== null) {
+        throw new Error("BIP341 NUMS root must be public-only");
+    }
+    let branch;
+    let child;
+    try {
+        branch = root.deriveChild(NUMS_BRANCH);
+        child = branch.deriveChild(BIP341_NUMS_CHILD_INDEX);
+    }
+    catch {
+        throw new NonExactBip32DerivationError("BIP32 rejected the requested NUMS derivation");
+    }
+    if (branch.index !== NUMS_BRANCH || child.index !== BIP341_NUMS_CHILD_INDEX) {
+        throw new NonExactBip32DerivationError("BIP32 skipped an invalid NUMS derivation index");
+    }
+    if (!child.publicKey) {
+        throw new Error("Failed to derive BIP341 NUMS internal key");
+    }
+    return {
+        rootCompressed,
+        chainCode,
+        extendedPublicKey: root.publicExtendedKey,
+        internalCompressed: child.publicKey,
+        internalXonly: child.publicKey.slice(1),
+    };
+}

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

@@ -0,0 +1,5 @@
+/** 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 { BuildVaultOptions, BuiltVault, User, VaultContract } from "./types.ts";
+export declare function buildAdminRequiredThenKofN(adminXonly: Uint8Array, allXonly: Uint8Array[], t: number): Uint8Array;
+export declare function buildVault(contract: VaultContract, companyUsers: User[], network?: BTC_NETWORK, options?: BuildVaultOptions): BuiltVault;