@bitgo/wasm-utxo 1.21.0 → 1.23.0

package/dist/cjs/js/bip322/index.d.ts

@@ -0,0 +1,236 @@
+/**
+ * BIP-0322 Generic Signed Message Format
+ *
+ * This module implements BIP-0322 for BitGo fixed-script wallets.
+ * It allows proving control of wallet addresses by signing arbitrary messages.
+ *
+ * @example
+ * ```typescript
+ * import { bip322, fixedScriptWallet } from '@bitgo/wasm-utxo';
+ *
+ * // Create wallet keys
+ * const walletKeys = fixedScriptWallet.RootWalletKeys.from([userXpub, backupXpub, bitgoXpub]);
+ *
+ * // Create an empty PSBT for BIP-0322 (version 0 required)
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add BIP-0322 inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign the input
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ *
+ * // Verify the input
+ * bip322.verifyBip322PsbtInput(psbt, idx0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * ```
+ */
+import { BitGoPsbt, type NetworkName, type ScriptId, type SignPath } from "../fixedScriptWallet/BitGoPsbt.js";
+import { type WalletKeysArg } from "../fixedScriptWallet/RootWalletKeys.js";
+import { type OutputScriptType } from "../fixedScriptWallet/scriptType.js";
+import { Transaction } from "../transaction.js";
+export type { OutputScriptType };
+/**
+ * Parameters for adding a BIP-0322 input to a PSBT
+ */
+export type AddBip322InputParams = {
+    /** The message to sign (UTF-8 string) */
+    message: string;
+    /** The wallet script location (chain and index) */
+    scriptId: ScriptId;
+    /** The wallet's root keys */
+    rootWalletKeys: WalletKeysArg;
+    /**
+     * Sign path for taproot inputs (required for p2tr/p2trMusig2).
+     * Specifies which two keys will sign the message.
+     */
+    signPath?: SignPath;
+    /** Custom tag for message hashing (default: "BIP0322-signed-message") */
+    tag?: string;
+};
+/**
+ * Parameters for verifying a BIP-0322 input
+ */
+export type VerifyBip322InputParams = {
+    /** The message that was signed */
+    message: string;
+    /** The wallet script location (chain and index) */
+    scriptId: ScriptId;
+    /** The wallet's root keys */
+    rootWalletKeys: WalletKeysArg;
+    /** Custom tag if one was used during signing */
+    tag?: string;
+};
+/**
+ * Parameters for verifying a BIP-0322 transaction input
+ */
+export type VerifyBip322TxInputParams = VerifyBip322InputParams & {
+    /** Network name (default: "bitcoin") */
+    network?: NetworkName;
+};
+/**
+ * Add a BIP-0322 message input to an existing BitGoPsbt
+ *
+ * The PSBT must have version 0 per BIP-0322 specification. Use
+ * `BitGoPsbt.createEmpty(network, walletKeys, { version: 0 })` to create one.
+ *
+ * On the first input added, this also adds the required OP_RETURN output.
+ *
+ * @param psbt - The BitGoPsbt to add the input to (must have version 0)
+ * @param params - Input parameters including message, scriptId, and wallet keys
+ * @returns The index of the added input
+ *
+ * @example
+ * ```typescript
+ * // Create a BIP-0322 PSBT
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "I control this address",
+ *   scriptId: { chain: 10, index: 5 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign with user and bitgo keys
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ * ```
+ */
+export declare function addBip322Input(psbt: BitGoPsbt, params: AddBip322InputParams): number;
+/**
+ * Verify a single input of a BIP-0322 transaction proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Extract and verify the transaction
+ * psbt.finalizeAllInputs();
+ * const txBytes = psbt.extractTransaction();
+ * const tx = Transaction.fromBytes(txBytes, "bitcoin");
+ *
+ * bip322.verifyBip322TxInput(tx, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ *   network: "bitcoin",
+ * });
+ * ```
+ */
+export declare function verifyBip322TxInput(tx: Transaction, inputIndex: number, params: VerifyBip322TxInputParams): void;
+/** Signer key name */
+export type SignerName = "user" | "backup" | "bitgo";
+/** Triple of hex-encoded pubkeys [user, backup, bitgo] */
+export type PubkeyTriple = [string, string, string];
+/**
+ * Parameters for verifying a BIP-0322 input with pubkeys
+ */
+export type VerifyBip322WithPubkeysParams = {
+    /** The message that was signed */
+    message: string;
+    /** Hex-encoded pubkeys [user, backup, bitgo] */
+    pubkeys: PubkeyTriple;
+    /** Script type */
+    scriptType: OutputScriptType;
+    /** For taproot types, whether script path was used */
+    isScriptPath?: boolean;
+    /** Custom tag if one was used during signing */
+    tag?: string;
+};
+/**
+ * Parameters for verifying a BIP-0322 transaction input with pubkeys
+ */
+export type VerifyBip322TxWithPubkeysParams = VerifyBip322WithPubkeysParams;
+/**
+ * Verify a single input of a BIP-0322 PSBT proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the wallet keys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @returns An array of signer names ("user", "backup", "bitgo") that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input
+ * const signers = bip322.verifyBip322PsbtInput(psbt, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * console.log(signers); // ["user", "bitgo"]
+ * ```
+ */
+export declare function verifyBip322PsbtInput(psbt: BitGoPsbt, inputIndex: number, params: VerifyBip322InputParams): SignerName[];
+/**
+ * Verify a single input of a BIP-0322 PSBT proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the provided pubkeys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input with pubkeys
+ * const signerIndices = bip322.verifyBip322PsbtInputWithPubkeys(psbt, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2shP2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+export declare function verifyBip322PsbtInputWithPubkeys(psbt: BitGoPsbt, inputIndex: number, params: VerifyBip322WithPubkeysParams): number[];
+/**
+ * Verify a single input of a BIP-0322 transaction proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed transaction input with pubkeys
+ * const signerIndices = bip322.verifyBip322TxInputWithPubkeys(tx, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+export declare function verifyBip322TxInputWithPubkeys(tx: Transaction, inputIndex: number, params: VerifyBip322TxWithPubkeysParams): number[];

package/dist/cjs/js/bip322/index.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * BIP-0322 Generic Signed Message Format
+ *
+ * This module implements BIP-0322 for BitGo fixed-script wallets.
+ * It allows proving control of wallet addresses by signing arbitrary messages.
+ *
+ * @example
+ * ```typescript
+ * import { bip322, fixedScriptWallet } from '@bitgo/wasm-utxo';
+ *
+ * // Create wallet keys
+ * const walletKeys = fixedScriptWallet.RootWalletKeys.from([userXpub, backupXpub, bitgoXpub]);
+ *
+ * // Create an empty PSBT for BIP-0322 (version 0 required)
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add BIP-0322 inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign the input
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ *
+ * // Verify the input
+ * bip322.verifyBip322PsbtInput(psbt, idx0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addBip322Input = addBip322Input;
+exports.verifyBip322TxInput = verifyBip322TxInput;
+exports.verifyBip322PsbtInput = verifyBip322PsbtInput;
+exports.verifyBip322PsbtInputWithPubkeys = verifyBip322PsbtInputWithPubkeys;
+exports.verifyBip322TxInputWithPubkeys = verifyBip322TxInputWithPubkeys;
+const wasm_utxo_js_1 = require("../wasm/wasm_utxo.js");
+const RootWalletKeys_js_1 = require("../fixedScriptWallet/RootWalletKeys.js");
+/**
+ * Add a BIP-0322 message input to an existing BitGoPsbt
+ *
+ * The PSBT must have version 0 per BIP-0322 specification. Use
+ * `BitGoPsbt.createEmpty(network, walletKeys, { version: 0 })` to create one.
+ *
+ * On the first input added, this also adds the required OP_RETURN output.
+ *
+ * @param psbt - The BitGoPsbt to add the input to (must have version 0)
+ * @param params - Input parameters including message, scriptId, and wallet keys
+ * @returns The index of the added input
+ *
+ * @example
+ * ```typescript
+ * // Create a BIP-0322 PSBT
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "I control this address",
+ *   scriptId: { chain: 10, index: 5 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign with user and bitgo keys
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ * ```
+ */
+function addBip322Input(psbt, params) {
+    const keys = RootWalletKeys_js_1.RootWalletKeys.from(params.rootWalletKeys);
+    return wasm_utxo_js_1.Bip322Namespace.add_bip322_input(psbt.wasm, params.message, params.scriptId.chain, params.scriptId.index, keys.wasm, params.signPath?.signer, params.signPath?.cosigner, params.tag);
+}
+/**
+ * Verify a single input of a BIP-0322 transaction proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Extract and verify the transaction
+ * psbt.finalizeAllInputs();
+ * const txBytes = psbt.extractTransaction();
+ * const tx = Transaction.fromBytes(txBytes, "bitcoin");
+ *
+ * bip322.verifyBip322TxInput(tx, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ *   network: "bitcoin",
+ * });
+ * ```
+ */
+function verifyBip322TxInput(tx, inputIndex, params) {
+    const keys = RootWalletKeys_js_1.RootWalletKeys.from(params.rootWalletKeys);
+    const network = params.network ?? "bitcoin";
+    wasm_utxo_js_1.Bip322Namespace.verify_bip322_tx_input(tx.wasm, inputIndex, params.message, params.scriptId.chain, params.scriptId.index, keys.wasm, network, params.tag);
+}
+/**
+ * Verify a single input of a BIP-0322 PSBT proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the wallet keys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @returns An array of signer names ("user", "backup", "bitgo") that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input
+ * const signers = bip322.verifyBip322PsbtInput(psbt, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * console.log(signers); // ["user", "bitgo"]
+ * ```
+ */
+function verifyBip322PsbtInput(psbt, inputIndex, params) {
+    const keys = RootWalletKeys_js_1.RootWalletKeys.from(params.rootWalletKeys);
+    return wasm_utxo_js_1.Bip322Namespace.verify_bip322_psbt_input(psbt.wasm, inputIndex, params.message, params.scriptId.chain, params.scriptId.index, keys.wasm, params.tag);
+}
+/**
+ * Verify a single input of a BIP-0322 PSBT proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the provided pubkeys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input with pubkeys
+ * const signerIndices = bip322.verifyBip322PsbtInputWithPubkeys(psbt, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2shP2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+function verifyBip322PsbtInputWithPubkeys(psbt, inputIndex, params) {
+    return Array.from(wasm_utxo_js_1.Bip322Namespace.verify_bip322_psbt_input_with_pubkeys(psbt.wasm, inputIndex, params.message, params.pubkeys, params.scriptType, params.isScriptPath, params.tag));
+}
+/**
+ * Verify a single input of a BIP-0322 transaction proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed transaction input with pubkeys
+ * const signerIndices = bip322.verifyBip322TxInputWithPubkeys(tx, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+function verifyBip322TxInputWithPubkeys(tx, inputIndex, params) {
+    return Array.from(wasm_utxo_js_1.Bip322Namespace.verify_bip322_tx_input_with_pubkeys(tx.wasm, inputIndex, params.message, params.pubkeys, params.scriptType, params.isScriptPath, params.tag));
+}

package/dist/cjs/js/fixedScriptWallet/Dimensions.d.ts

@@ -47,6 +47,10 @@ export declare class Dimensions {
      * Combine with another Dimensions instance
      */
     plus(other: Dimensions): Dimensions;
+    /**
+     * Multiply dimensions by a scalar
+     */
+    times(n: number): Dimensions;
     /**
      * Whether any inputs are segwit (affects overhead calculation)
      */
@@ -61,5 +65,23 @@ export declare class Dimensions {
      * @param size - "min" or "max", defaults to "max"
      */
     getVSize(size?: "min" | "max"): number;
+    /**
+     * Get input weight only (min or max)
+     * @param size - "min" or "max", defaults to "max"
+     */
+    getInputWeight(size?: "min" | "max"): number;
+    /**
+     * Get input virtual size (min or max)
+     * @param size - "min" or "max", defaults to "max"
+     */
+    getInputVSize(size?: "min" | "max"): number;
+    /**
+     * Get output weight
+     */
+    getOutputWeight(): number;
+    /**
+     * Get output virtual size
+     */
+    getOutputVSize(): number;
 }
 export {};

package/dist/cjs/js/fixedScriptWallet/Dimensions.js

@@ -59,6 +59,12 @@ class Dimensions {
     plus(other) {
         return new Dimensions(this._wasm.plus(other._wasm));
     }
+    /**
+     * Multiply dimensions by a scalar
+     */
+    times(n) {
+        return new Dimensions(this._wasm.times(n));
+    }
     /**
      * Whether any inputs are segwit (affects overhead calculation)
      */
@@ -79,5 +85,31 @@ class Dimensions {
     getVSize(size = "max") {
         return this._wasm.get_vsize(size);
     }
+    /**
+     * Get input weight only (min or max)
+     * @param size - "min" or "max", defaults to "max"
+     */
+    getInputWeight(size = "max") {
+        return this._wasm.get_input_weight(size);
+    }
+    /**
+     * Get input virtual size (min or max)
+     * @param size - "min" or "max", defaults to "max"
+     */
+    getInputVSize(size = "max") {
+        return this._wasm.get_input_vsize(size);
+    }
+    /**
+     * Get output weight
+     */
+    getOutputWeight() {
+        return this._wasm.get_output_weight();
+    }
+    /**
+     * Get output virtual size
+     */
+    getOutputVSize() {
+        return this._wasm.get_output_vsize();
+    }
 }
 exports.Dimensions = Dimensions;

package/dist/cjs/js/fixedScriptWallet/chains.d.ts

@@ -0,0 +1,56 @@
+import type { OutputScriptType } from "./scriptType.js";
+/** All valid chain codes as a const tuple */
+export declare const chainCodes: readonly [0, 1, 10, 11, 20, 21, 30, 31, 40, 41];
+/** A valid chain code value */
+export type ChainCode = (typeof chainCodes)[number];
+/** Whether a chain is for receiving (external) or change (internal) addresses */
+export type Scope = "internal" | "external";
+/**
+ * ChainCode namespace with utility functions for working with chain codes.
+ */
+export declare const ChainCode: {
+    /**
+     * Check if a value is a valid chain code.
+     *
+     * @example
+     * ```typescript
+     * if (ChainCode.is(maybeChain)) {
+     *   // maybeChain is now typed as ChainCode
+     *   const scope = ChainCode.scope(maybeChain);
+     * }
+     * ```
+     */
+    is(n: unknown): n is ChainCode;
+    /**
+     * Get the chain code for a script type and scope.
+     *
+     * @example
+     * ```typescript
+     * const externalP2wsh = ChainCode.value("p2wsh", "external"); // 20
+     * const internalP2tr = ChainCode.value("p2trLegacy", "internal"); // 31
+     * ```
+     */
+    value(scriptType: OutputScriptType | "p2tr", scope: Scope): ChainCode;
+    /**
+     * Get the scope (external/internal) for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scope(0);  // "external"
+     * ChainCode.scope(1);  // "internal"
+     * ChainCode.scope(20); // "external"
+     * ```
+     */
+    scope(chainCode: ChainCode): Scope;
+    /**
+     * Get the script type for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scriptType(0);  // "p2sh"
+     * ChainCode.scriptType(20); // "p2wsh"
+     * ChainCode.scriptType(40); // "p2trMusig2"
+     * ```
+     */
+    scriptType(chainCode: ChainCode): OutputScriptType;
+};

package/dist/cjs/js/fixedScriptWallet/chains.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainCode = exports.chainCodes = void 0;
+/**
+ * Chain code utilities for BitGo fixed-script wallets.
+ *
+ * Chain codes define the derivation path component for different script types
+ * and scopes (external/internal) in the format `m/0/0/{chain}/{index}`.
+ */
+const wasm_utxo_js_1 = require("../wasm/wasm_utxo.js");
+/** All valid chain codes as a const tuple */
+exports.chainCodes = [0, 1, 10, 11, 20, 21, 30, 31, 40, 41];
+// Build static lookup tables once at module load time
+const chainCodeSet = new Set(exports.chainCodes);
+const chainToMeta = new Map();
+const scriptTypeToChain = new Map();
+// Initialize from WASM (called once at load time)
+function assertChainCode(n) {
+    if (!chainCodeSet.has(n)) {
+        throw new Error(`Invalid chain code from WASM: ${n}`);
+    }
+    return n;
+}
+function assertScope(s) {
+    if (s !== "internal" && s !== "external") {
+        throw new Error(`Invalid scope from WASM: ${s}`);
+    }
+    return s;
+}
+for (const tuple of wasm_utxo_js_1.FixedScriptWalletNamespace.chain_code_table()) {
+    if (!Array.isArray(tuple) || tuple.length !== 3) {
+        throw new Error(`Invalid chain_code_table entry: expected [number, string, string]`);
+    }
+    const [rawCode, rawScriptType, rawScope] = tuple;
+    if (typeof rawCode !== "number") {
+        throw new Error(`Invalid chain code type: ${typeof rawCode}`);
+    }
+    if (typeof rawScriptType !== "string") {
+        throw new Error(`Invalid scriptType type: ${typeof rawScriptType}`);
+    }
+    if (typeof rawScope !== "string") {
+        throw new Error(`Invalid scope type: ${typeof rawScope}`);
+    }
+    const code = assertChainCode(rawCode);
+    const scriptType = rawScriptType;
+    const scope = assertScope(rawScope);
+    chainToMeta.set(code, { scope, scriptType });
+    let entry = scriptTypeToChain.get(scriptType);
+    if (!entry) {
+        entry = {};
+        scriptTypeToChain.set(scriptType, entry);
+    }
+    entry[scope] = code;
+}
+/**
+ * ChainCode namespace with utility functions for working with chain codes.
+ */
+exports.ChainCode = {
+    /**
+     * Check if a value is a valid chain code.
+     *
+     * @example
+     * ```typescript
+     * if (ChainCode.is(maybeChain)) {
+     *   // maybeChain is now typed as ChainCode
+     *   const scope = ChainCode.scope(maybeChain);
+     * }
+     * ```
+     */
+    is(n) {
+        return typeof n === "number" && chainCodeSet.has(n);
+    },
+    /**
+     * Get the chain code for a script type and scope.
+     *
+     * @example
+     * ```typescript
+     * const externalP2wsh = ChainCode.value("p2wsh", "external"); // 20
+     * const internalP2tr = ChainCode.value("p2trLegacy", "internal"); // 31
+     * ```
+     */
+    value(scriptType, scope) {
+        // legacy alias for p2trLegacy
+        if (scriptType === "p2tr") {
+            scriptType = "p2trLegacy";
+        }
+        const entry = scriptTypeToChain.get(scriptType);
+        if (!entry) {
+            throw new Error(`Invalid scriptType: ${scriptType}`);
+        }
+        return entry[scope];
+    },
+    /**
+     * Get the scope (external/internal) for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scope(0);  // "external"
+     * ChainCode.scope(1);  // "internal"
+     * ChainCode.scope(20); // "external"
+     * ```
+     */
+    scope(chainCode) {
+        const meta = chainToMeta.get(chainCode);
+        if (!meta)
+            throw new Error(`Invalid chainCode: ${chainCode}`);
+        return meta.scope;
+    },
+    /**
+     * Get the script type for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scriptType(0);  // "p2sh"
+     * ChainCode.scriptType(20); // "p2wsh"
+     * ChainCode.scriptType(40); // "p2trMusig2"
+     * ```
+     */
+    scriptType(chainCode) {
+        const meta = chainToMeta.get(chainCode);
+        if (!meta)
+            throw new Error(`Invalid chainCode: ${chainCode}`);
+        return meta.scriptType;
+    },
+};