@btc-vision/bitcoin 6.5.5 → 7.0.0-alpha.0

package/src/payments/p2tr.ts

@@ -1,10 +1,26 @@
+/**
+ * Pay-to-Taproot (P2TR) payment class.
+ *
+ * P2TR is the Taproot output type (BIP341). It supports both key-path spending
+ * (single signature) and script-path spending (merkle tree of scripts).
+ *
+ * @packageDocumentation
+ */
+
 import { bech32m } from 'bech32';
-import { Buffer as NBuffer } from 'buffer';
 import { fromBech32 } from '../bech32utils.js';
-import { getEccLib } from '../ecc_lib.js';
-import { bitcoin as BITCOIN_NETWORK } from '../networks.js';
+import { getEccLib } from '../ecc/context.js';
+import { bitcoin as BITCOIN_NETWORK, type Network } from '../networks.js';
 import * as bscript from '../script.js';
-import { isTaptree, stacksEqual, TAPLEAF_VERSION_MASK, typeforce as typef } from '../types.js';
+import {
+    stacksEqual,
+    TAPLEAF_VERSION_MASK,
+    type Bytes32,
+    type Script,
+    type SchnorrSignature,
+    type Taptree,
+    type XOnlyPublicKey,
+} from '../types.js';
 import {
     findScriptPath,
     LEAF_VERSION_TAPSCRIPT,
@@ -12,298 +28,774 @@ import {
     tapleafHash,
     toHashTree,
     tweakKey,
+    type HashTree,
 } from './bip341.js';
-import { P2TRPayment, PaymentOpts, PaymentType } from './types.js';
-import * as lazy from './lazy.js';
+import { concat, equals } from '../io/index.js';
+import { PaymentType, type P2TRPayment, type PaymentOpts, type ScriptRedeem } from './types.js';
 
 const OPS = bscript.opcodes;
 const TAPROOT_WITNESS_VERSION = 0x01;
 const ANNEX_PREFIX = 0x50;
 
 /**
- * Creates a Pay-to-Taproot (P2TR) payment object.
+ * Pay-to-Taproot (P2TR) payment class.
+ *
+ * Creates locking scripts of the form: `OP_1 {x-only pubkey}`
+ *
+ * Key-path spending witness: `[signature]`
+ * Script-path spending witness: `[script inputs..., script, control block]`
+ *
+ * @example
+ * ```typescript
+ * import { P2TR } from '@btc-vision/bitcoin';
+ *
+ * // Key-path only (no scripts)
+ * const keyOnly = P2TR.fromInternalPubkey(internalPubkey);
+ * console.log(keyOnly.address); // bc1p... address
  *
- * @param a - The payment object containing the necessary data for P2TR.
- * @param opts - Optional payment options.
- * @returns The P2TR payment object.
- * @throws {TypeError} If the provided data is invalid or insufficient.
+ * // With script tree
+ * const withScripts = P2TR.fromInternalPubkey(internalPubkey, scriptTree);
+ *
+ * // Decode an existing output
+ * const decoded = P2TR.fromOutput(scriptPubKey);
+ * console.log(decoded.pubkey); // 32-byte x-only pubkey
+ * ```
  */
-export function p2tr(a: Omit<P2TRPayment, 'name'>, opts?: PaymentOpts): P2TRPayment {
-    if (
-        !a.address &&
-        !a.output &&
-        !a.pubkey &&
-        !a.internalPubkey &&
-        !(a.witness && a.witness.length > 1)
-    )
-        throw new TypeError('Not enough data');
+export class P2TR {
+    // Static public fields
+    static readonly NAME = PaymentType.P2TR;
+
+    // Private instance fields
+    readonly #network: Network;
+    readonly #opts: Required<PaymentOpts>;
+
+    // Input data (provided by user)
+    #inputAddress?: string | undefined;
+    #inputPubkey?: Uint8Array | undefined;
+    #inputInternalPubkey?: Uint8Array | undefined;
+    #inputHash?: Uint8Array | undefined;
+    #inputScriptTree?: Taptree | undefined;
+    #inputSignature?: Uint8Array | undefined;
+    #inputOutput?: Uint8Array | undefined;
+    #inputWitness?: Uint8Array[] | undefined;
+    #inputRedeem?: ScriptRedeem | undefined;
+    #inputRedeemVersion?: number | undefined;
+
+    // Cached computed values
+    #address?: string | undefined;
+    #pubkey?: XOnlyPublicKey | undefined;
+    #internalPubkey?: XOnlyPublicKey | undefined;
+    #hash?: Bytes32 | undefined;
+    #signature?: SchnorrSignature | undefined;
+    #output?: Script | undefined;
+    #redeem?: ScriptRedeem | undefined;
+    #redeemVersion?: number | undefined;
+    #witness?: Uint8Array[] | undefined;
+
+    // Cache flags
+    #addressComputed = false;
+    #pubkeyComputed = false;
+    #internalPubkeyComputed = false;
+    #hashComputed = false;
+    #signatureComputed = false;
+    #outputComputed = false;
+    #redeemComputed = false;
+    #redeemVersionComputed = false;
+    #witnessComputed = false;
+
+    // Decoded address cache
+    #decodedAddress?: { version: number; prefix: string; data: Uint8Array } | undefined;
+    #decodedAddressComputed = false;
+
+    // Witness without annex
+    #witnessWithoutAnnex?: Uint8Array[] | undefined;
+    #witnessWithoutAnnexComputed = false;
+
+    // Hash tree cache
+    #hashTree?: HashTree | undefined;
+    #hashTreeComputed = false;
+
+    /**
+     * Creates a new P2TR payment instance.
+     *
+     * @param params - Payment parameters
+     * @param params.address - Bech32m encoded address (bc1p...)
+     * @param params.pubkey - x-only output pubkey (32 bytes)
+     * @param params.internalPubkey - x-only internal pubkey (32 bytes)
+     * @param params.hash - Merkle root (32 bytes, or empty for key-path only)
+     * @param params.scriptTree - Full script tree definition
+     * @param params.signature - Schnorr signature (for key-path spending)
+     * @param params.output - The scriptPubKey
+     * @param params.witness - The witness stack
+     * @param params.redeem - Redeem script for script-path spending
+     * @param params.redeemVersion - Leaf version (defaults to LEAF_VERSION_TAPSCRIPT)
+     * @param params.network - Network parameters (defaults to mainnet)
+     * @param opts - Payment options
+     * @param opts.validate - Whether to validate inputs (default: true)
+     *
+     * @throws {TypeError} If validation is enabled and data is invalid
+     */
+    constructor(
+        params: {
+            address?: string | undefined;
+            pubkey?: Uint8Array | undefined;
+            internalPubkey?: Uint8Array | undefined;
+            hash?: Uint8Array | undefined;
+            scriptTree?: Taptree | undefined;
+            signature?: Uint8Array | undefined;
+            output?: Uint8Array | undefined;
+            witness?: Uint8Array[] | undefined;
+            redeem?: ScriptRedeem | undefined;
+            redeemVersion?: number | undefined;
+            network?: Network | undefined;
+        },
+        opts?: PaymentOpts,
+    ) {
+        this.#network = params.network ?? BITCOIN_NETWORK;
+        this.#opts = {
+            validate: opts?.validate ?? true,
+            allowIncomplete: opts?.allowIncomplete ?? false,
+        };
 
-    opts = Object.assign({ validate: true }, opts || {});
+        // Store input data
+        this.#inputAddress = params.address;
+        this.#inputPubkey = params.pubkey;
+        this.#inputInternalPubkey = params.internalPubkey;
+        this.#inputHash = params.hash;
+        this.#inputScriptTree = params.scriptTree;
+        this.#inputSignature = params.signature;
+        this.#inputOutput = params.output;
+        this.#inputWitness = params.witness;
+        this.#inputRedeem = params.redeem;
+        this.#inputRedeemVersion = params.redeemVersion;
+
+        // Validate if requested
+        if (this.#opts.validate) {
+            this.#validate();
+        }
+    }
 
-    typef(
-        {
-            address: typef.maybe(typef.String),
-            input: typef.maybe(typef.BufferN(0)),
-            network: typef.maybe(typef.Object),
-            output: typef.maybe(typef.BufferN(34)),
-            internalPubkey: typef.maybe(typef.BufferN(32)),
-            hash: typef.maybe(typef.BufferN(32)), // merkle root hash, the tweak
-            pubkey: typef.maybe(typef.BufferN(32)), // tweaked with `hash` from `internalPubkey`
-            signature: typef.maybe(typef.anyOf(typef.BufferN(64), typef.BufferN(65))),
-            witness: typef.maybe(typef.arrayOf(typef.Buffer)),
-            scriptTree: typef.maybe(isTaptree),
-            redeem: typef.maybe({
-                output: typef.maybe(typef.Buffer), // tapleaf script
-                redeemVersion: typef.maybe(typef.Number), // tapleaf version
-                witness: typef.maybe(typef.arrayOf(typef.Buffer)),
-            }),
-            redeemVersion: typef.maybe(typef.Number),
-        },
-        a,
-    );
+    // Public getters
+
+    /**
+     * Payment type discriminant.
+     */
+    get name(): typeof PaymentType.P2TR {
+        return PaymentType.P2TR;
+    }
+
+    /**
+     * Network parameters.
+     */
+    get network(): Network {
+        return this.#network;
+    }
 
-    const _address = lazy.value(() => {
-        return fromBech32(a.address!);
-    });
+    /**
+     * Bech32m encoded address (bc1p... for mainnet).
+     */
+    get address(): string | undefined {
+        if (!this.#addressComputed) {
+            this.#address = this.#computeAddress();
+            this.#addressComputed = true;
+        }
+        return this.#address;
+    }
 
-    // remove annex if present, ignored by taproot
-    const _witness = lazy.value(() => {
-        if (!a.witness || !a.witness.length) return;
-        if (a.witness.length >= 2 && a.witness[a.witness.length - 1][0] === ANNEX_PREFIX) {
-            return a.witness.slice(0, -1);
+    /**
+     * x-only output pubkey (32 bytes).
+     * This is the tweaked pubkey that appears in the output.
+     */
+    get pubkey(): XOnlyPublicKey | undefined {
+        if (!this.#pubkeyComputed) {
+            this.#pubkey = this.#computePubkey();
+            this.#pubkeyComputed = true;
         }
-        return a.witness.slice();
-    });
+        return this.#pubkey;
+    }
 
-    const _hashTree = lazy.value(() => {
-        if (a.scriptTree) return toHashTree(a.scriptTree);
-        if (a.hash) return { hash: a.hash };
-        return;
-    });
+    /**
+     * x-only internal pubkey (32 bytes).
+     * This is the untweaked pubkey before adding the merkle root tweak.
+     */
+    get internalPubkey(): XOnlyPublicKey | undefined {
+        if (!this.#internalPubkeyComputed) {
+            this.#internalPubkey = this.#computeInternalPubkey();
+            this.#internalPubkeyComputed = true;
+        }
+        return this.#internalPubkey;
+    }
 
-    const network = a.network || BITCOIN_NETWORK;
-    const o: P2TRPayment = {
-        name: PaymentType.P2TR,
-        network,
-    };
+    /**
+     * Merkle root hash (32 bytes).
+     * Present when a script tree is defined.
+     */
+    get hash(): Bytes32 | undefined {
+        if (!this.#hashComputed) {
+            this.#hash = this.#computeHash();
+            this.#hashComputed = true;
+        }
+        return this.#hash;
+    }
 
-    lazy.prop(o, 'address', () => {
-        if (!o.pubkey) return;
+    /**
+     * Schnorr signature (for key-path spending).
+     */
+    get signature(): SchnorrSignature | undefined {
+        if (!this.#signatureComputed) {
+            this.#signature = this.#computeSignature();
+            this.#signatureComputed = true;
+        }
+        return this.#signature;
+    }
 
-        const words = bech32m.toWords(o.pubkey);
+    /**
+     * The scriptPubKey: `OP_1 {32-byte x-only pubkey}`
+     */
+    get output(): Script | undefined {
+        if (!this.#outputComputed) {
+            this.#output = this.#computeOutput();
+            this.#outputComputed = true;
+        }
+        return this.#output;
+    }
+
+    /**
+     * Redeem script information (for script-path spending).
+     */
+    get redeem(): ScriptRedeem | undefined {
+        if (!this.#redeemComputed) {
+            this.#redeem = this.#computeRedeem();
+            this.#redeemComputed = true;
+        }
+        return this.#redeem;
+    }
+
+    /**
+     * Leaf version (defaults to LEAF_VERSION_TAPSCRIPT = 0xc0).
+     */
+    get redeemVersion(): number {
+        if (!this.#redeemVersionComputed) {
+            this.#redeemVersion = this.#computeRedeemVersion();
+            this.#redeemVersionComputed = true;
+        }
+        return this.#redeemVersion ?? LEAF_VERSION_TAPSCRIPT;
+    }
+
+    /**
+     * Witness stack.
+     * Key-path: `[signature]`
+     * Script-path: `[script inputs..., script, control block]`
+     */
+    get witness(): Uint8Array[] | undefined {
+        if (!this.#witnessComputed) {
+            this.#witness = this.#computeWitness();
+            this.#witnessComputed = true;
+        }
+        return this.#witness;
+    }
+
+    // Static factory methods
+
+    /**
+     * Creates a P2TR payment from an internal pubkey (key-path only).
+     *
+     * @param internalPubkey - x-only internal pubkey (32 bytes)
+     * @param scriptTree - Optional script tree
+     * @param network - Network parameters (defaults to mainnet)
+     * @returns A new P2TR payment instance
+     *
+     * @example
+     * ```typescript
+     * // Key-path only
+     * const p2tr = P2TR.fromInternalPubkey(internalPubkey);
+     *
+     * // With script tree
+     * const withScripts = P2TR.fromInternalPubkey(internalPubkey, scriptTree);
+     * ```
+     */
+    static fromInternalPubkey(
+        internalPubkey: XOnlyPublicKey,
+        scriptTree?: Taptree,
+        network?: Network,
+    ): P2TR {
+        return new P2TR({ internalPubkey, scriptTree, network });
+    }
+
+    /**
+     * Creates a P2TR payment from a bech32m address.
+     *
+     * @param address - Bech32m encoded address (bc1p...)
+     * @param network - Network parameters (defaults to mainnet)
+     * @returns A new P2TR payment instance
+     */
+    static fromAddress(address: string, network?: Network): P2TR {
+        return new P2TR({ address, network });
+    }
+
+    /**
+     * Creates a P2TR payment from a scriptPubKey.
+     *
+     * @param output - The scriptPubKey
+     * @param network - Network parameters (defaults to mainnet)
+     * @returns A new P2TR payment instance
+     */
+    static fromOutput(output: Uint8Array, network?: Network): P2TR {
+        return new P2TR({ output, network });
+    }
+
+    /**
+     * Creates a P2TR payment from a signature (for key-path spending).
+     *
+     * @param signature - Schnorr signature
+     * @param internalPubkey - x-only internal pubkey
+     * @param network - Network parameters (defaults to mainnet)
+     * @returns A new P2TR payment instance
+     */
+    static fromSignature(
+        signature: SchnorrSignature,
+        internalPubkey?: XOnlyPublicKey,
+        network?: Network,
+    ): P2TR {
+        return new P2TR({ signature, internalPubkey, network });
+    }
+
+    // Private helper methods
+
+    #getDecodedAddress(): { version: number; prefix: string; data: Uint8Array } | undefined {
+        if (!this.#decodedAddressComputed) {
+            if (this.#inputAddress) {
+                const decoded = fromBech32(this.#inputAddress);
+                if (decoded) {
+                    this.#decodedAddress = {
+                        version: decoded.version,
+                        prefix: decoded.prefix,
+                        data: decoded.data,
+                    };
+                }
+            }
+            this.#decodedAddressComputed = true;
+        }
+        return this.#decodedAddress;
+    }
+
+    #getWitnessWithoutAnnex(): Uint8Array[] | undefined {
+        if (!this.#witnessWithoutAnnexComputed) {
+            if (this.#inputWitness && this.#inputWitness.length > 0) {
+                // Remove annex if present
+                if (
+                    this.#inputWitness.length >= 2 &&
+                    this.#inputWitness[this.#inputWitness.length - 1]![0] === ANNEX_PREFIX
+                ) {
+                    this.#witnessWithoutAnnex = this.#inputWitness.slice(0, -1);
+                } else {
+                    this.#witnessWithoutAnnex = this.#inputWitness.slice();
+                }
+            }
+            this.#witnessWithoutAnnexComputed = true;
+        }
+        return this.#witnessWithoutAnnex;
+    }
+
+    #getHashTree(): HashTree | undefined {
+        if (!this.#hashTreeComputed) {
+            if (this.#inputScriptTree) {
+                this.#hashTree = toHashTree(this.#inputScriptTree);
+            } else if (this.#inputHash) {
+                this.#hashTree = { hash: this.#inputHash as Bytes32 };
+            }
+            this.#hashTreeComputed = true;
+        }
+        return this.#hashTree;
+    }
+
+    // Private computation methods
+
+    #computeAddress(): string | undefined {
+        if (this.#inputAddress) {
+            return this.#inputAddress;
+        }
+        const pk = this.pubkey;
+        if (!pk) return undefined;
+
+        const words = bech32m.toWords(pk);
         words.unshift(TAPROOT_WITNESS_VERSION);
-        return bech32m.encode(network.bech32, words);
-    });
+        return bech32m.encode(this.#network.bech32, words);
+    }
 
-    lazy.prop(o, 'hash', () => {
-        const hashTree = _hashTree();
-        if (hashTree) return hashTree.hash;
+    #computePubkey(): XOnlyPublicKey | undefined {
+        if (this.#inputPubkey) {
+            return this.#inputPubkey as XOnlyPublicKey;
+        }
+        if (this.#inputOutput) {
+            return this.#inputOutput.subarray(2) as XOnlyPublicKey;
+        }
+        if (this.#inputAddress) {
+            return this.#getDecodedAddress()?.data as XOnlyPublicKey | undefined;
+        }
+        const internalPk = this.internalPubkey;
+        if (internalPk) {
+            const tweakedKey = tweakKey(internalPk, this.hash);
+            if (tweakedKey) {
+                return tweakedKey.x as XOnlyPublicKey;
+            }
+        }
+        return undefined;
+    }
+
+    #computeInternalPubkey(): XOnlyPublicKey | undefined {
+        if (this.#inputInternalPubkey) {
+            return this.#inputInternalPubkey as XOnlyPublicKey;
+        }
+        const witness = this.#getWitnessWithoutAnnex();
+        if (witness && witness.length > 1) {
+            return witness[witness.length - 1]!.subarray(1, 33) as XOnlyPublicKey;
+        }
+        return undefined;
+    }
 
-        const w = _witness();
+    #computeHash(): Bytes32 | undefined {
+        const hashTree = this.#getHashTree();
+        if (hashTree) {
+            return hashTree.hash as Bytes32;
+        }
+
+        const w = this.#getWitnessWithoutAnnex();
         if (w && w.length > 1) {
-            const controlBlock = w[w.length - 1];
-            const leafVersion = controlBlock[0] & TAPLEAF_VERSION_MASK;
-            const script = w[w.length - 2];
+            const controlBlock = w[w.length - 1]!;
+            const leafVersion = controlBlock[0]! & TAPLEAF_VERSION_MASK;
+            const script = w[w.length - 2]!;
             const leafHash = tapleafHash({
                 output: script,
                 version: leafVersion,
             });
-            return rootHashFromPath(controlBlock, leafHash);
+            return rootHashFromPath(controlBlock, leafHash) as Bytes32;
         }
 
         return undefined;
-    });
-    lazy.prop(o, 'output', () => {
-        if (!o.pubkey) return;
-        return bscript.compile([OPS.OP_1, o.pubkey]);
-    });
-    lazy.prop(o, 'redeemVersion', () => {
-        if (a.redeemVersion) return a.redeemVersion;
-        if (a.redeem && a.redeem.redeemVersion !== undefined && a.redeem.redeemVersion !== null) {
-            return a.redeem.redeemVersion;
+    }
+
+    #computeSignature(): SchnorrSignature | undefined {
+        if (this.#inputSignature) {
+            return this.#inputSignature as SchnorrSignature;
+        }
+        const witness = this.#getWitnessWithoutAnnex();
+        if (witness && witness.length === 1) {
+            return witness[0] as SchnorrSignature;
+        }
+        return undefined;
+    }
+
+    #computeOutput(): Script | undefined {
+        if (this.#inputOutput) {
+            return this.#inputOutput as Script;
         }
+        const pk = this.pubkey;
+        if (!pk) return undefined;
 
-        return LEAF_VERSION_TAPSCRIPT;
-    });
-    lazy.prop(o, 'redeem', () => {
-        const witness = _witness(); // witness without annex
-        if (!witness || witness.length < 2) return;
+        return bscript.compile([OPS.OP_1, pk]) as Script;
+    }
 
+    #computeRedeem(): ScriptRedeem | undefined {
+        if (this.#inputRedeem) {
+            return this.#inputRedeem;
+        }
+        const witness = this.#getWitnessWithoutAnnex();
+        if (!witness || witness.length < 2) {
+            return undefined;
+        }
         return {
-            output: witness[witness.length - 2],
+            output: witness[witness.length - 2] as Script,
             witness: witness.slice(0, -2),
-            redeemVersion: witness[witness.length - 1][0] & TAPLEAF_VERSION_MASK,
+            redeemVersion: witness[witness.length - 1]![0]! & TAPLEAF_VERSION_MASK,
         };
-    });
-    lazy.prop(o, 'pubkey', () => {
-        if (a.pubkey) return a.pubkey;
-        if (a.output) return a.output.subarray(2);
-        if (a.address) return _address().data;
-        if (o.internalPubkey) {
-            const tweakedKey = tweakKey(o.internalPubkey, o.hash);
-            if (tweakedKey) return tweakedKey.x;
-        }
-    });
-    lazy.prop(o, 'internalPubkey', () => {
-        if (a.internalPubkey) return a.internalPubkey;
-        const witness = _witness();
-        if (witness && witness.length > 1) return witness[witness.length - 1].subarray(1, 33);
-    });
-    lazy.prop(o, 'signature', () => {
-        if (a.signature) return a.signature;
-        const witness = _witness(); // witness without annex
-        if (!witness || witness.length !== 1) return;
-        return witness[0];
-    });
-
-    lazy.prop(o, 'witness', () => {
-        if (a.witness) return a.witness;
-        const hashTree = _hashTree();
-        if (hashTree && a.redeem && a.redeem.output && a.internalPubkey) {
+    }
+
+    #computeRedeemVersion(): number | undefined {
+        if (this.#inputRedeemVersion !== undefined) {
+            return this.#inputRedeemVersion;
+        }
+        if (
+            this.#inputRedeem &&
+            this.#inputRedeem.redeemVersion !== undefined &&
+            this.#inputRedeem.redeemVersion !== null
+        ) {
+            return this.#inputRedeem.redeemVersion;
+        }
+        return LEAF_VERSION_TAPSCRIPT;
+    }
+
+    #computeWitness(): Uint8Array[] | undefined {
+        if (this.#inputWitness) {
+            return this.#inputWitness;
+        }
+
+        const hashTree = this.#getHashTree();
+        if (hashTree && this.#inputRedeem?.output && this.#inputInternalPubkey) {
             const leafHash = tapleafHash({
-                output: a.redeem.output,
-                version: o.redeemVersion,
+                output: this.#inputRedeem.output,
+                version: this.redeemVersion,
             });
             const path = findScriptPath(hashTree, leafHash);
-            if (!path) return;
-            const outputKey = tweakKey(a.internalPubkey, hashTree.hash);
-            if (!outputKey) return;
-            const controlBock = NBuffer.concat(
-                [NBuffer.from([o.redeemVersion! | outputKey.parity]), a.internalPubkey].concat(
-                    path,
-                ),
-            );
-            return [a.redeem.output, controlBock];
-        }
-        if (a.signature) return [a.signature];
-    });
-
-    // extended validation
-    if (opts.validate) {
-        let pubkey: Buffer = NBuffer.from([]);
-        if (a.address) {
-            if (network && network.bech32 !== _address().prefix)
+            if (!path) return undefined;
+
+            const outputKey = tweakKey(this.#inputInternalPubkey as XOnlyPublicKey, hashTree.hash);
+            if (!outputKey) return undefined;
+
+            const version = this.redeemVersion ?? 0xc0;
+            const controlBlock = concat([
+                new Uint8Array([version | outputKey.parity]),
+                this.#inputInternalPubkey,
+                ...path,
+            ]);
+            return [this.#inputRedeem.output, controlBlock];
+        }
+
+        if (this.#inputSignature) {
+            return [this.#inputSignature];
+        }
+
+        return undefined;
+    }
+
+    // Validation
+
+    #validate(): void {
+        let pubkey: Uint8Array = new Uint8Array(0);
+
+        if (this.#inputAddress) {
+            const addr = this.#getDecodedAddress();
+            if (!addr) {
+                throw new TypeError('Invalid address');
+            }
+            if (this.#network && this.#network.bech32 !== addr.prefix) {
                 throw new TypeError('Invalid prefix or Network mismatch');
-            if (_address().version !== TAPROOT_WITNESS_VERSION)
+            }
+            if (addr.version !== TAPROOT_WITNESS_VERSION) {
                 throw new TypeError('Invalid address version');
-            if (_address().data.length !== 32) throw new TypeError('Invalid address data');
-            pubkey = _address().data;
+            }
+            if (addr.data.length !== 32) {
+                throw new TypeError('Invalid address data');
+            }
+            pubkey = addr.data;
         }
 
-        if (a.pubkey) {
-            if (pubkey.length > 0 && !pubkey.equals(a.pubkey))
+        if (this.#inputPubkey) {
+            if (pubkey.length > 0 && !equals(pubkey, this.#inputPubkey)) {
                 throw new TypeError('Pubkey mismatch');
-            else pubkey = a.pubkey;
+            } else {
+                pubkey = this.#inputPubkey;
+            }
         }
 
-        if (a.output) {
-            if (a.output.length !== 34 || a.output[0] !== OPS.OP_1 || a.output[1] !== 0x20)
+        if (this.#inputOutput) {
+            if (
+                this.#inputOutput.length !== 34 ||
+                this.#inputOutput[0] !== OPS.OP_1 ||
+                this.#inputOutput[1] !== 0x20
+            ) {
                 throw new TypeError('Output is invalid');
-            if (pubkey.length > 0 && !pubkey.equals(a.output.subarray(2)))
+            }
+            if (pubkey.length > 0 && !equals(pubkey, this.#inputOutput.subarray(2))) {
                 throw new TypeError('Pubkey mismatch');
-            else pubkey = a.output.subarray(2);
+            } else {
+                pubkey = this.#inputOutput.subarray(2);
+            }
         }
 
-        if (a.internalPubkey) {
-            const tweakedKey = tweakKey(a.internalPubkey, o.hash);
-            if (pubkey.length > 0 && !pubkey.equals(tweakedKey!.x))
+        if (this.#inputInternalPubkey) {
+            const tweakedKey = tweakKey(this.#inputInternalPubkey as XOnlyPublicKey, this.hash);
+            if (!tweakedKey) {
+                throw new TypeError('Invalid internal pubkey');
+            }
+            if (pubkey.length > 0 && !equals(pubkey, tweakedKey.x)) {
                 throw new TypeError('Pubkey mismatch');
-            else pubkey = tweakedKey!.x;
+            } else {
+                pubkey = tweakedKey.x;
+            }
         }
 
-        /*if (pubkey && pubkey.length) {
-           if (!getEccLib().isXOnlyPoint(pubkey))
-               throw new TypeError('Invalid pubkey for p2tr');
-       }*/
+        const hashTree = this.#getHashTree();
 
-        const hashTree = _hashTree();
-
-        if (a.hash && hashTree) {
-            if (!a.hash.equals(hashTree.hash)) throw new TypeError('Hash mismatch');
+        if (this.#inputHash && hashTree) {
+            if (!equals(this.#inputHash, hashTree.hash)) {
+                throw new TypeError('Hash mismatch');
+            }
         }
 
-        if (a.redeem && a.redeem.output && hashTree) {
+        if (this.#inputRedeem?.output && hashTree) {
             const leafHash = tapleafHash({
-                output: a.redeem.output,
-                version: o.redeemVersion,
+                output: this.#inputRedeem.output,
+                version: this.redeemVersion,
             });
-            if (!findScriptPath(hashTree, leafHash))
+            if (!findScriptPath(hashTree, leafHash)) {
                 throw new TypeError('Redeem script not in tree');
+            }
         }
 
-        const witness = _witness();
+        const witness = this.#getWitnessWithoutAnnex();
 
-        // compare the provided redeem data with the one computed from witness
-        if (a.redeem && o.redeem) {
-            if (a.redeem.redeemVersion) {
-                if (a.redeem.redeemVersion !== o.redeem.redeemVersion)
+        // Compare provided redeem with computed from witness
+        if (this.#inputRedeem && this.redeem) {
+            if (this.#inputRedeem.redeemVersion) {
+                if (this.#inputRedeem.redeemVersion !== this.redeem.redeemVersion) {
                     throw new TypeError('Redeem.redeemVersion and witness mismatch');
+                }
             }
 
-            if (a.redeem.output) {
-                if (bscript.decompile(a.redeem.output)!.length === 0)
+            if (this.#inputRedeem.output) {
+                const decompiled = bscript.decompile(this.#inputRedeem.output);
+                if (!decompiled || decompiled.length === 0) {
                     throw new TypeError('Redeem.output is invalid');
+                }
 
-                // output redeem is constructed from the witness
-                if (o.redeem.output && !a.redeem.output.equals(o.redeem.output))
+                if (this.redeem.output && !equals(this.#inputRedeem.output, this.redeem.output)) {
                     throw new TypeError('Redeem.output and witness mismatch');
+                }
             }
-            if (a.redeem.witness) {
-                if (o.redeem.witness && !stacksEqual(a.redeem.witness, o.redeem.witness))
+            if (this.#inputRedeem.witness) {
+                if (
+                    this.redeem.witness &&
+                    !stacksEqual(this.#inputRedeem.witness, this.redeem.witness)
+                ) {
                     throw new TypeError('Redeem.witness and witness mismatch');
+                }
             }
         }
 
-        if (witness && witness.length) {
+        if (witness && witness.length > 0) {
             if (witness.length === 1) {
-                // key spending
-                if (a.signature && !a.signature.equals(witness[0]))
+                // Key-path spending
+                if (this.#inputSignature && !equals(this.#inputSignature!, witness[0]!)) {
                     throw new TypeError('Signature mismatch');
+                }
             } else {
-                // script path spending
-                const controlBlock = witness[witness.length - 1];
-                if (controlBlock.length < 33)
+                // Script-path spending
+                const controlBlock = witness[witness.length - 1]!;
+                if (controlBlock.length < 33) {
                     throw new TypeError(
                         `The control-block length is too small. Got ${controlBlock.length}, expected min 33.`,
                     );
+                }
 
-                if ((controlBlock.length - 33) % 32 !== 0)
+                if ((controlBlock.length - 33) % 32 !== 0) {
                     throw new TypeError(
                         `The control-block length of ${controlBlock.length} is incorrect!`,
                     );
+                }
 
                 const m = (controlBlock.length - 33) / 32;
-                if (m > 128)
+                if (m > 128) {
                     throw new TypeError(`The script path is too long. Got ${m}, expected max 128.`);
+                }
 
-                const internalPubkey = controlBlock.subarray(1, 33);
-                if (a.internalPubkey && !a.internalPubkey.equals(internalPubkey))
+                const internalPk = controlBlock.subarray(1, 33);
+                if (this.#inputInternalPubkey && !equals(this.#inputInternalPubkey!, internalPk)) {
                     throw new TypeError('Internal pubkey mismatch');
+                }
 
-                if (!getEccLib().isXOnlyPoint(internalPubkey))
+                if (!getEccLib().isXOnlyPoint(internalPk)) {
                     throw new TypeError('Invalid internalPubkey for p2tr witness');
+                }
 
-                const leafVersion = controlBlock[0] & TAPLEAF_VERSION_MASK;
-                const script = witness[witness.length - 2];
+                const leafVersion = controlBlock[0]! & TAPLEAF_VERSION_MASK;
+                const script = witness[witness.length - 2]!;
 
                 const leafHash = tapleafHash({
                     output: script,
                     version: leafVersion,
                 });
-                const hash = rootHashFromPath(controlBlock, leafHash);
+                const computedHash = rootHashFromPath(controlBlock, leafHash);
 
-                const outputKey = tweakKey(internalPubkey, hash);
-                if (!outputKey)
-                    // todo: needs test data
+                const outputKey = tweakKey(internalPk as XOnlyPublicKey, computedHash);
+                if (!outputKey) {
                     throw new TypeError('Invalid outputKey for p2tr witness');
+                }
 
-                if (pubkey.length && !pubkey.equals(outputKey.x))
+                if (pubkey.length > 0 && !equals(pubkey, outputKey.x)) {
                     throw new TypeError('Pubkey mismatch for p2tr witness');
+                }
 
-                if (outputKey.parity !== (controlBlock[0] & 1)) throw new Error('Incorrect parity');
+                if (outputKey.parity !== (controlBlock[0]! & 1)) {
+                    throw new Error('Incorrect parity');
+                }
             }
         }
     }
 
-    return Object.assign(o, a);
+    /**
+     * Converts to a plain P2TRPayment object for backwards compatibility.
+     *
+     * @returns A P2TRPayment object
+     */
+    toPayment(): P2TRPayment {
+        return {
+            name: this.name,
+            network: this.network,
+            address: this.address,
+            pubkey: this.pubkey,
+            internalPubkey: this.internalPubkey,
+            hash: this.hash,
+            scriptTree: this.#inputScriptTree,
+            signature: this.signature,
+            output: this.output,
+            redeem: this.redeem,
+            redeemVersion: this.redeemVersion,
+            witness: this.witness,
+        };
+    }
+}
+
+/**
+ * Creates a Pay-to-Taproot (P2TR) payment object.
+ *
+ * This is the legacy factory function for backwards compatibility.
+ * For new code, prefer using the P2TR class directly.
+ *
+ * @param a - The payment object containing the necessary data
+ * @param opts - Optional payment options
+ * @returns The P2TR payment object
+ * @throws {TypeError} If the required data is not provided or if the data is invalid
+ *
+ * @example
+ * ```typescript
+ * import { p2tr } from '@btc-vision/bitcoin';
+ *
+ * // Key-path only
+ * const payment = p2tr({ internalPubkey });
+ *
+ * // With script tree
+ * const withScripts = p2tr({ internalPubkey, scriptTree });
+ * ```
+ */
+export function p2tr(a: Omit<P2TRPayment, 'name'>, opts?: PaymentOpts): P2TRPayment {
+    if (
+        !a.address &&
+        !a.output &&
+        !a.pubkey &&
+        !a.internalPubkey &&
+        !(a.witness && a.witness.length > 1)
+    ) {
+        throw new TypeError('Not enough data');
+    }
+
+    const instance = new P2TR(
+        {
+            address: a.address,
+            pubkey: a.pubkey,
+            internalPubkey: a.internalPubkey,
+            hash: a.hash,
+            scriptTree: a.scriptTree,
+            signature: a.signature,
+            output: a.output,
+            witness: a.witness,
+            redeem: a.redeem,
+            redeemVersion: a.redeemVersion,
+            network: a.network,
+        },
+        opts,
+    );
+
+    // Return a merged object for backwards compatibility
+    return Object.assign(instance.toPayment(), a);
 }