@btc-vision/bitcoin 7.0.0-alpha.1 → 7.0.0-alpha.3

package/src/ecc/types.ts

@@ -1,147 +1,16 @@
 /**
  * ECC (Elliptic Curve Cryptography) type definitions.
- * Defines interfaces for secp256k1 operations used in Taproot and signatures.
+ *
+ * Re-exports {@link CryptoBackend} from `@btc-vision/ecpair` as the canonical
+ * interface for secp256k1 operations. The legacy `EccLib` name is kept as a
+ * type alias for backward compatibility.
  *
  * @packageDocumentation
  */
 
-import type { Bytes32, PrivateKey, PublicKey, SchnorrSignature, Signature, XOnlyPublicKey, } from '../branded.js';
-
-/**
- * Parity of the y-coordinate for an x-only public key.
- * - 0: even y-coordinate
- * - 1: odd y-coordinate
- */
-export type Parity = 0 | 1;
-
-/**
- * Result of x-only point addition with tweak.
- */
-export interface XOnlyPointAddTweakResult {
-    /** Parity of the resulting y-coordinate (0 = even, 1 = odd) */
-    readonly parity: Parity;
-    /** The resulting x-only public key */
-    readonly xOnlyPubkey: XOnlyPublicKey;
-}
+export type { CryptoBackend, XOnlyPointAddTweakResult, Parity } from '@btc-vision/ecpair';
 
 /**
- * Interface for the ECC library used by this library.
- * This is compatible with tiny-secp256k1 and @noble/secp256k1.
- *
- * @example
- * ```typescript
- * import { EccLib, initEccLib } from '@btc-vision/bitcoin';
- * import * as secp256k1 from 'tiny-secp256k1';
- *
- * // tiny-secp256k1 implements EccLib
- * const ecc: EccLib = secp256k1;
- * initEccLib(ecc);
- * ```
+ * @deprecated Use {@link CryptoBackend} from `@btc-vision/ecpair` instead.
  */
-export interface EccLib {
-    /**
-     * Checks if a 32-byte value is a valid x-only public key.
-     *
-     * @param p - 32-byte x-coordinate
-     * @returns True if the point is valid on the secp256k1 curve
-     */
-    isXOnlyPoint(p: Uint8Array): boolean;
-
-    /**
-     * Adds a tweak to an x-only public key.
-     *
-     * @param p - 32-byte x-only public key
-     * @param tweak - 32-byte scalar to add
-     * @returns The tweaked public key with parity, or null if result is invalid
-     */
-    xOnlyPointAddTweak(p: XOnlyPublicKey, tweak: Bytes32): XOnlyPointAddTweakResult | null;
-
-    /**
-     * Signs a 32-byte message hash with a private key (ECDSA).
-     * Optional - only needed for signing operations.
-     *
-     * @param hash - 32-byte message hash
-     * @param privateKey - 32-byte private key
-     * @returns DER-encoded signature
-     */
-    sign?(hash: Bytes32, privateKey: PrivateKey): Signature;
-
-    /**
-     * Signs a 32-byte message hash with a private key (Schnorr/BIP340).
-     * Optional - only needed for Taproot key-path signing.
-     *
-     * @param hash - 32-byte message hash
-     * @param privateKey - 32-byte private key
-     * @returns 64-byte Schnorr signature
-     */
-    signSchnorr?(hash: Bytes32, privateKey: PrivateKey): SchnorrSignature;
-
-    /**
-     * Verifies an ECDSA signature.
-     * Optional - only needed for signature verification.
-     *
-     * @param hash - 32-byte message hash
-     * @param publicKey - 33 or 65-byte public key
-     * @param signature - DER-encoded signature
-     * @returns True if signature is valid
-     */
-    verify?(hash: Bytes32, publicKey: PublicKey, signature: Signature): boolean;
-
-    /**
-     * Verifies a Schnorr/BIP340 signature.
-     * Optional - only needed for Taproot signature verification.
-     *
-     * @param hash - 32-byte message hash
-     * @param publicKey - 32-byte x-only public key
-     * @param signature - 64-byte Schnorr signature
-     * @returns True if signature is valid
-     */
-    verifySchnorr?(hash: Bytes32, publicKey: XOnlyPublicKey, signature: SchnorrSignature): boolean;
-
-    /**
-     * Derives a public key from a private key.
-     * Optional - only needed for key derivation.
-     *
-     * @param privateKey - 32-byte private key
-     * @param compressed - Whether to return compressed (33-byte) or uncompressed (65-byte)
-     * @returns The public key, or null if private key is invalid
-     */
-    pointFromScalar?(privateKey: PrivateKey, compressed?: boolean): PublicKey | null;
-
-    /**
-     * Computes the x-only public key from a private key.
-     * Optional - only needed for Taproot key derivation.
-     *
-     * @param privateKey - 32-byte private key
-     * @returns 32-byte x-only public key, or null if private key is invalid
-     */
-    xOnlyPointFromScalar?(privateKey: PrivateKey): XOnlyPublicKey | null;
-
-    /**
-     * Converts a full public key to x-only format.
-     * Optional - only needed when working with x-only keys.
-     *
-     * @param pubkey - 33 or 65-byte public key
-     * @returns 32-byte x-only public key
-     */
-    xOnlyPointFromPoint?(pubkey: PublicKey): XOnlyPublicKey;
-
-    /**
-     * Adds a scalar to a private key.
-     * Optional - only needed for key tweaking.
-     *
-     * @param privateKey - 32-byte private key
-     * @param tweak - 32-byte scalar to add
-     * @returns The tweaked private key, or null if result is invalid
-     */
-    privateAdd?(privateKey: PrivateKey, tweak: Bytes32): PrivateKey | null;
-
-    /**
-     * Negates a private key.
-     * Optional - only needed for Taproot parity handling.
-     *
-     * @param privateKey - 32-byte private key
-     * @returns The negated private key
-     */
-    privateNegate?(privateKey: PrivateKey): PrivateKey;
-}
+export type { CryptoBackend as EccLib } from '@btc-vision/ecpair';

package/src/index.ts

@@ -39,7 +39,41 @@ export * as script from './script.js';
 export { Block } from './block.js';
 /** @hidden */
 export * from './crypto.js';
-export * from './psbt.js';
+export {
+    Psbt,
+    PsbtCache,
+    PsbtSigner,
+    PsbtFinalizer,
+    PsbtTransaction,
+    transactionFromBuffer,
+    getFinalScripts,
+    prepareFinalScripts,
+} from './psbt.js';
+export type {
+    TransactionInput,
+    PsbtTxInput,
+    TransactionOutput,
+    PsbtTxOutput,
+    ValidateSigFunction,
+    PsbtBaseExtended,
+    PsbtOptsOptional,
+    PsbtOpts,
+    PsbtInputExtended,
+    PsbtOutputExtended,
+    PsbtOutputExtendedScript,
+    HDSigner,
+    HDSignerAsync,
+    Signer,
+    SignerAsync,
+    TaprootHashCheckSigner,
+    PsbtCacheInterface,
+    TxCacheNumberKey,
+    ScriptType,
+    AllScriptType,
+    GetScriptReturn,
+    FinalScriptsFunc,
+    FinalTaprootScriptsFunc,
+} from './psbt.js';
 /** @hidden */
 export { opcodes } from './opcodes.js';
 export { Transaction } from './transaction.js';
@@ -48,7 +82,7 @@ export type { TaprootHashCache } from './transaction.js';
 export type { Network } from './networks.js';
 /** @hidden */
 export { initEccLib, getEccLib, EccContext } from './ecc/context.js';
-export type { EccLib } from './ecc/types.js';
+export type { CryptoBackend, EccLib } from './ecc/types.js';
 export { PaymentType } from './payments/index.js';
 export type {
     Payment,

package/src/opcodes.ts

@@ -273,8 +273,25 @@ export const opcodes: Opcodes = {
     OP_INVALIDOPCODE: 255,
 };
 
-export const REVERSE_OPS: { [key: number]: string } = {};
-for (const op of Object.keys(opcodes)) {
-    const code = opcodes[op as keyof Opcodes];
-    REVERSE_OPS[code] = op;
+let _reverseOps: { [key: number]: string } | undefined;
+
+/**
+ * Returns the reverse mapping from opcode number to opcode name.
+ * Lazily computed on first call.
+ */
+export function getReverseOps(): { [key: number]: string } {
+    if (!_reverseOps) {
+        _reverseOps = {};
+        for (const op of Object.keys(opcodes)) {
+            const code = opcodes[op as keyof Opcodes];
+            _reverseOps[code] = op;
+        }
+    }
+    return _reverseOps;
 }
+
+/**
+ * @deprecated Use {@link getReverseOps}() for lazy initialization.
+ * This eagerly-initialized alias exists for backward compatibility.
+ */
+export const REVERSE_OPS: { [key: number]: string } = getReverseOps();

package/src/payments/p2tr.ts

@@ -9,11 +9,11 @@
 
 import { bech32m } from 'bech32';
 import { fromBech32 } from '../bech32utils.js';
-import { getEccLib } from '../ecc/context.js';
 import { bitcoin as BITCOIN_NETWORK, type Network } from '../networks.js';
 import * as bscript from '../script.js';
 import {
     type Bytes32,
+    isXOnlyPublicKey,
     type SchnorrSignature,
     type Script,
     stacksEqual,
@@ -716,7 +716,7 @@ export class P2TR {
                     throw new TypeError('Internal pubkey mismatch');
                 }
 
-                if (!getEccLib().isXOnlyPoint(internalPk)) {
+                if (!isXOnlyPublicKey(internalPk)) {
                     throw new TypeError('Invalid internalPubkey for p2tr witness');
                 }
 

package/src/psbt/PsbtCache.ts

@@ -0,0 +1,325 @@
+import type { PsbtInput, PsbtOutput } from 'bip174';
+import * as bscript from '../script.js';
+import type { TaprootHashCache, Transaction } from '../transaction.js';
+import type { PublicKey, Satoshi, Script, XOnlyPublicKey } from '../types.js';
+import { isP2TR, isP2WPKH, pubkeyInScript } from './psbtutils.js';
+import { getMeaningfulScript, isPubkeyLike, isSigLike, scriptWitnessToWitnessStack, } from './utils.js';
+import type { GetScriptReturn, PrevOut, PsbtOpts } from './types.js';
+import { isFinalized } from './validation.js';
+import { isUnknownSegwitVersion } from '../address.js';
+
+/**
+ * Internal PSBT cache for computed values.
+ * Wraps all cache management previously handled by a plain interface + scattered helper functions.
+ */
+export class PsbtCache {
+    public readonly nonWitnessUtxoTxCache: Transaction[];
+    public readonly nonWitnessUtxoBufCache: Uint8Array[];
+    public readonly txInCache: Record<string, number>;
+    public readonly tx: Transaction;
+    public unsafeSignNonSegwit: boolean;
+    public hasSignatures: boolean;
+    public fee: number | undefined;
+    public feeRate: number | undefined;
+    public extractedTx: Transaction | undefined;
+    public prevOuts: readonly PrevOut[] | undefined;
+    public signingScripts: readonly Script[] | undefined;
+    public values: readonly Satoshi[] | undefined;
+    public taprootHashCache: TaprootHashCache | undefined;
+
+    public constructor(tx: Transaction) {
+        this.nonWitnessUtxoTxCache = [];
+        this.nonWitnessUtxoBufCache = [];
+        this.txInCache = {};
+        this.tx = tx;
+        this.unsafeSignNonSegwit = false;
+        this.hasSignatures = false;
+    }
+
+    /**
+     * Invalidates cached computed values.
+     * @param scope - 'full' clears everything (for input changes), 'outputs' clears fee/extract/taproot caches
+     */
+    public invalidate(scope: 'full' | 'outputs'): void {
+        this.fee = undefined;
+        this.feeRate = undefined;
+        this.extractedTx = undefined;
+        this.taprootHashCache = undefined;
+        if (scope === 'full') {
+            this.prevOuts = undefined;
+            this.signingScripts = undefined;
+            this.values = undefined;
+        }
+    }
+
+    public addNonWitnessTxCache(
+        input: PsbtInput,
+        inputIndex: number,
+        txFromBuffer: (buf: Uint8Array) => Transaction,
+    ): void {
+        if (!input.nonWitnessUtxo) throw new Error('nonWitnessUtxo is required');
+        if (input === null || input === Object.prototype) {
+            throw new Error('Invalid input object');
+        }
+        const nonWitnessUtxoBuf = input.nonWitnessUtxo;
+        this.nonWitnessUtxoBufCache[inputIndex] = nonWitnessUtxoBuf;
+        this.nonWitnessUtxoTxCache[inputIndex] = txFromBuffer(nonWitnessUtxoBuf);
+    }
+
+    public getNonWitnessUtxoTx(
+        input: PsbtInput,
+        inputIndex: number,
+        txFromBuffer: (buf: Uint8Array) => Transaction,
+    ): Transaction {
+        const cached = this.nonWitnessUtxoTxCache[inputIndex];
+        if (!cached) {
+            this.addNonWitnessTxCache(input, inputIndex, txFromBuffer);
+        }
+        return this.nonWitnessUtxoTxCache[inputIndex]!;
+    }
+
+    public getScriptFromUtxo(
+        inputIndex: number,
+        input: PsbtInput,
+        txFromBuffer: (buf: Uint8Array) => Transaction,
+    ): Script {
+        const { script } = this.getScriptAndAmountFromUtxo(inputIndex, input, txFromBuffer);
+        return script;
+    }
+
+    public getScriptAndAmountFromUtxo(
+        inputIndex: number,
+        input: PsbtInput,
+        txFromBuffer: (buf: Uint8Array) => Transaction,
+    ): { script: Script; value: Satoshi } {
+        if (input.witnessUtxo !== undefined) {
+            return {
+                script: input.witnessUtxo.script as Script,
+                value: input.witnessUtxo.value as Satoshi,
+            };
+        } else if (input.nonWitnessUtxo !== undefined) {
+            const nonWitnessUtxoTx = this.getNonWitnessUtxoTx(input, inputIndex, txFromBuffer);
+            const o = nonWitnessUtxoTx.outs[this.tx.ins[inputIndex]!.index]!;
+            return { script: o.script, value: o.value };
+        } else {
+            throw new Error("Can't find pubkey in input without Utxo data");
+        }
+    }
+
+    public computeFee(
+        inputs: PsbtInput[],
+        disableOutputChecks: boolean = false,
+        txFromBuffer?: (buf: Uint8Array) => Transaction,
+    ): number {
+        if (!inputs.every(isFinalized)) throw new Error('PSBT must be finalized to calculate fee');
+        if (this.fee !== undefined) return this.fee;
+        let tx: Transaction;
+        let mustFinalize = true;
+        if (this.extractedTx) {
+            tx = this.extractedTx;
+            mustFinalize = false;
+        } else {
+            tx = this.tx.clone();
+        }
+        const { fee } = this.finalizeAndComputeAmounts(
+            inputs,
+            tx,
+            mustFinalize,
+            disableOutputChecks,
+            txFromBuffer,
+        );
+        return fee;
+    }
+
+    public computeFeeRate(
+        inputs: PsbtInput[],
+        disableOutputChecks: boolean = false,
+        txFromBuffer?: (buf: Uint8Array) => Transaction,
+    ): number {
+        if (!inputs.every(isFinalized))
+            throw new Error('PSBT must be finalized to calculate fee rate');
+        if (this.feeRate !== undefined) return this.feeRate;
+        let tx: Transaction;
+        let mustFinalize = true;
+        if (this.extractedTx) {
+            tx = this.extractedTx;
+            mustFinalize = false;
+        } else {
+            tx = this.tx.clone();
+        }
+        const { feeRate } = this.finalizeAndComputeAmounts(
+            inputs,
+            tx,
+            mustFinalize,
+            disableOutputChecks,
+            txFromBuffer,
+        );
+        return feeRate;
+    }
+
+    public checkFees(opts: PsbtOpts): void {
+        const feeRate = this.feeRate;
+        if (!this.extractedTx) throw new Error('Transaction not extracted');
+        if (feeRate === undefined) throw new Error('Fee rate not computed');
+        const vsize = this.extractedTx.virtualSize();
+        const satoshis = feeRate * vsize;
+        if (feeRate >= opts.maximumFeeRate) {
+            throw new Error(
+                `Warning: You are paying around ${(satoshis / 1e8).toFixed(8)} in ` +
+                    `fees, which is ${feeRate} satoshi per byte for a transaction ` +
+                    `with a VSize of ${vsize} bytes (segwit counted as 0.25 byte per ` +
+                    `byte). Use setMaximumFeeRate method to raise your threshold, or ` +
+                    `pass true to the first arg of extractTransaction.`,
+            );
+        }
+    }
+
+    public pubkeyInInput(
+        pubkey: PublicKey,
+        input: PsbtInput,
+        inputIndex: number,
+        txFromBuffer: (buf: Uint8Array) => Transaction,
+    ): boolean {
+        const script = this.getScriptFromUtxo(inputIndex, input, txFromBuffer);
+        const { meaningfulScript } = getMeaningfulScript(
+            script,
+            inputIndex,
+            'input',
+            input.redeemScript,
+            input.witnessScript,
+        );
+        return pubkeyInScript(pubkey, meaningfulScript);
+    }
+
+    public pubkeyInOutput(pubkey: PublicKey, output: PsbtOutput, outputIndex: number): boolean {
+        const script = this.tx.outs[outputIndex]!.script;
+        const { meaningfulScript } = getMeaningfulScript(
+            script,
+            outputIndex,
+            'output',
+            output.redeemScript,
+            output.witnessScript,
+        );
+        return pubkeyInScript(pubkey, meaningfulScript);
+    }
+
+    public redeemFromFinalScriptSig(finalScript: Uint8Array | undefined): Uint8Array | undefined {
+        if (!finalScript) return;
+        const decomp = bscript.decompile(finalScript);
+        if (!decomp) return;
+        const lastItem = decomp[decomp.length - 1]!;
+        if (!(lastItem instanceof Uint8Array) || isPubkeyLike(lastItem) || isSigLike(lastItem))
+            return;
+        const sDecomp = bscript.decompile(lastItem);
+        if (!sDecomp) return;
+        return lastItem;
+    }
+
+    public redeemFromFinalWitnessScript(
+        finalScript: Uint8Array | undefined,
+    ): Uint8Array | undefined {
+        if (!finalScript) return;
+        const decomp = scriptWitnessToWitnessStack(finalScript);
+        const lastItem = decomp[decomp.length - 1]!;
+        if (isPubkeyLike(lastItem)) return;
+        const sDecomp = bscript.decompile(lastItem);
+        if (!sDecomp) return;
+        return lastItem;
+    }
+
+    /**
+     * Finalize transaction inputs and compute fee amounts.
+     * Returns computed values instead of mutating cache parameters directly.
+     */
+    public finalizeAndComputeAmounts(
+        inputs: PsbtInput[],
+        tx: Transaction,
+        mustFinalize: boolean,
+        disableOutputChecks?: boolean,
+        txFromBuffer?: (buf: Uint8Array) => Transaction,
+    ): { fee: number; feeRate: number } {
+        let inputAmount = 0n;
+        inputs.forEach((input, idx) => {
+            if (mustFinalize && input.finalScriptSig)
+                tx.ins[idx]!.script = input.finalScriptSig as Script;
+            if (mustFinalize && input.finalScriptWitness) {
+                tx.ins[idx]!.witness = scriptWitnessToWitnessStack(input.finalScriptWitness);
+            }
+            if (input.witnessUtxo) {
+                inputAmount += input.witnessUtxo.value;
+            } else if (input.nonWitnessUtxo) {
+                if (!txFromBuffer)
+                    throw new Error('txFromBuffer is required for nonWitnessUtxo inputs');
+                const nwTx = this.getNonWitnessUtxoTx(input, idx, txFromBuffer);
+                const vout = tx.ins[idx]!.index;
+                const out = nwTx.outs[vout]!;
+                inputAmount += out.value;
+            }
+        });
+        const outputAmount = tx.outs.reduce((total, o) => total + o.value, 0n);
+        const feeValue = inputAmount - outputAmount;
+        if (!disableOutputChecks) {
+            if (feeValue < 0n) {
+                throw new Error(
+                    `Outputs are spending more than Inputs ${inputAmount} < ${outputAmount}`,
+                );
+            }
+        }
+        const bytes = tx.virtualSize();
+        const fee = Number(feeValue);
+        const feeRate = Math.floor(fee / bytes);
+
+        this.fee = fee;
+        this.extractedTx = tx;
+        this.feeRate = feeRate;
+
+        return { fee, feeRate };
+    }
+
+    public getScriptFromInput(
+        inputIndex: number,
+        input: PsbtInput,
+        txFromBuffer: (buf: Uint8Array) => Transaction,
+    ): GetScriptReturn {
+        const res: GetScriptReturn = {
+            script: null,
+            isSegwit: false,
+            isP2SH: false,
+            isP2WSH: false,
+        };
+        res.isP2SH = !!input.redeemScript;
+        res.isP2WSH = !!input.witnessScript;
+        if (input.witnessScript) {
+            res.script = input.witnessScript as Script;
+        } else if (input.redeemScript) {
+            res.script = input.redeemScript as Script;
+        } else {
+            if (input.nonWitnessUtxo) {
+                const nonWitnessUtxoTx = this.getNonWitnessUtxoTx(input, inputIndex, txFromBuffer);
+                const prevoutIndex = this.tx.ins[inputIndex]!.index;
+                res.script = nonWitnessUtxoTx.outs[prevoutIndex]!.script;
+            } else if (input.witnessUtxo) {
+                res.script = input.witnessUtxo.script as Script;
+            }
+        }
+
+        if (input.witnessScript || (res.script && isP2WPKH(res.script))) {
+            res.isSegwit = true;
+        } else {
+            if (res.script && isUnknownSegwitVersion(res.script)) {
+                res.isSegwit = true;
+            }
+        }
+
+        return res;
+    }
+
+    public getPrevoutTaprootKey(
+        inputIndex: number,
+        input: PsbtInput,
+        txFromBuffer: (buf: Uint8Array) => Transaction,
+    ): XOnlyPublicKey | null {
+        const { script } = this.getScriptAndAmountFromUtxo(inputIndex, input, txFromBuffer);
+        return isP2TR(script) ? (script.subarray(2, 34) as XOnlyPublicKey) : null;
+    }
+}