@exodus/bip322-js 1.1.0-rc.0 → 1.1.0

package/dist/Verifier.js

@@ -1,118 +1,239 @@
-import BIP322 from "./BIP322";
-import { Address, BIP137 } from "./helpers";
-import * as bitcoin from '@exodus/bitcoinjs';
-import ecc from '@exodus/bitcoinerlab-secp256k1';
-import * as bitcoinMessage from 'bitcoinjs-message';
-import { decodeScriptSignature } from './bitcoinjs';
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Import dependencies
+const BIP322_1 = __importDefault(require("./BIP322"));
+const helpers_1 = require("./helpers");
+const bitcoin = __importStar(require("@exodus/bitcoinjs-lib"));
+const bitcoinerlab_secp256k1_1 = __importDefault(require("@exodus/bitcoinerlab-secp256k1"));
+const bitcoinMessage = __importStar(require("bitcoinjs-message"));
+const bitcoinjs_1 = require("./bitcoinjs");
+/**
+ * Class that handles BIP-322 signature verification.
+ * Reference: https://github.com/LegReq/bip0322-signatures/blob/master/BIP0322_verification.ipynb
+ */
 class Verifier {
+    /**
+     * Verify a BIP-322 signature from P2WPKH, P2SH-P2WPKH, and single-key-spend P2TR address.
+     * @param signerAddress Address of the signing address
+     * @param message message_challenge signed by the address
+     * @param signatureBase64 Signature produced by the signing address
+     * @returns True if the provided signature is a valid BIP-322 signature for the given message and address, false if otherwise
+     * @throws If the provided signature fails basic validation, or if unsupported address and signature are provided
+     */
     static verifySignature(signerAddress, message, signatureBase64) {
-        if (Address.isP2PKH(signerAddress) || BIP137.isBIP137Signature(signatureBase64)) {
+        // Handle legacy BIP-137 signature
+        // For P2PKH address, assume the signature is also a legacy signature
+        if (helpers_1.Address.isP2PKH(signerAddress) || helpers_1.BIP137.isBIP137Signature(signatureBase64)) {
             return this.verifyBIP137Signature(signerAddress, message, signatureBase64);
         }
-        const scriptPubKey = Address.convertAdressToScriptPubkey(signerAddress);
-        const toSpendTx = BIP322.buildToSpendTx(message, scriptPubKey);
-        const toSignTx = BIP322.buildToSignTx(toSpendTx.getId(), scriptPubKey);
+        // Convert address into corresponding script pubkey
+        const scriptPubKey = helpers_1.Address.convertAdressToScriptPubkey(signerAddress);
+        // Draft corresponding toSpend and toSign transaction using the message and script pubkey
+        const toSpendTx = BIP322_1.default.buildToSpendTx(message, scriptPubKey);
+        const toSignTx = BIP322_1.default.buildToSignTx(toSpendTx.getId(), scriptPubKey);
+        // Add the witness stack into the toSignTx
         toSignTx.updateInput(0, {
             finalScriptWitness: Buffer.from(signatureBase64, 'base64')
         });
+        // Obtain the signature within the witness components
         const witness = toSignTx.extractTransaction().ins[0].witness;
         const encodedSignature = witness[0];
-        if (Address.isP2WPKHWitness(witness)) {
+        // Branch depending on whether the signing address is a non-taproot or a taproot address
+        if (helpers_1.Address.isP2WPKHWitness(witness)) {
+            // For non-taproot segwit transaciton, public key is included as the second part of the witness data
             const publicKey = witness[1];
-            const { signature } = decodeScriptSignature(encodedSignature);
+            const { signature } = (0, bitcoinjs_1.decodeScriptSignature)(encodedSignature);
+            // Compute OP_HASH160(publicKey)
             const hashedPubkey = bitcoin.crypto.hash160(publicKey);
-            let hashToSign;
-            if (Address.isP2SH(signerAddress)) {
+            // Common path variable
+            let hashToSign; // Hash expected to be signed by the signing address
+            if (helpers_1.Address.isP2SH(signerAddress)) {
+                // P2SH-P2WPKH verification path
+                // Compute the hash that correspond to the toSignTx
                 hashToSign = this.getHashForSigP2SHInP2WPKH(toSignTx, hashedPubkey);
+                // The original locking script for P2SH-P2WPKH is OP_0 <PubKeyHash>
                 const lockingScript = Buffer.concat([Buffer.from([0x00, 0x14]), hashedPubkey]);
+                // Compute OP_HASH160(lockingScript)
                 const hashedLockingScript = bitcoin.crypto.hash160(lockingScript);
+                // For nested segwit (P2SH-P2WPKH) address, the hashed locking script is located from the 3rd byte to the last 2nd byte as OP_HASH160 <HASH> OP_EQUAL
                 const hashedLockingScriptInScriptPubKey = scriptPubKey.subarray(2, -1);
+                // Check if the P2SH locking script OP_HASH160 <HASH> OP_EQUAL is satisified
                 if (Buffer.compare(hashedLockingScript, hashedLockingScriptInScriptPubKey) !== 0) {
-                    return false;
+                    return false; // Reject signature if the hashed locking script is different from the hashed locking script in the scriptPubKey
                 }
             }
             else {
+                // P2WPKH verification path
+                // Compute the hash that correspond to the toSignTx
                 hashToSign = this.getHashForSigP2WPKH(toSignTx);
+                // For native segwit address, the hashed public key is located from the 3rd to the end as OP_0 <HASH>
                 const hashedPubkeyInScriptPubkey = scriptPubKey.subarray(2);
+                // Check if OP_HASH160(publicKey) === hashedPubkeyInScriptPubkey
                 if (Buffer.compare(hashedPubkey, hashedPubkeyInScriptPubkey) !== 0) {
-                    return false;
+                    return false; // Reject signature if the hashed public key did not match
                 }
             }
-            return ecc.verify(hashToSign, publicKey, signature);
+            // Computing OP_CHECKSIG in Javascript
+            return bitcoinerlab_secp256k1_1.default.verify(hashToSign, publicKey, signature);
         }
-        else if (Address.isP2TR(signerAddress)) {
-            if (!Address.isSingleKeyP2TRWitness(witness)) {
+        else if (helpers_1.Address.isP2TR(signerAddress)) {
+            // Check if the witness stack correspond to a single-key-spend P2TR address
+            if (!helpers_1.Address.isSingleKeyP2TRWitness(witness)) {
                 throw new Error('BIP-322 verification from script-spend P2TR is unsupported.');
             }
+            // For taproot address, the public key is located starting from the 3rd byte of the script public key
             const publicKey = scriptPubKey.subarray(2);
+            // Compute the hash to be signed by the signing address
+            // Reference: https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#user-content-Taproot_key_path_spending_signature_validation
             let hashToSign;
             let signature;
             if (encodedSignature.byteLength === 64) {
+                // If a BIP-341 signature is 64 bytes, the signature is signed using SIGHASH_DEFAULT 0x00 
                 hashToSign = this.getHashForSigP2TR(toSignTx, 0x00);
+                // And the entirety of the encoded signature is the actual signature
                 signature = encodedSignature;
             }
             else if (encodedSignature.byteLength === 65) {
+                // If a BIP-341 signature is 65 bytes, the signature is signed using SIGHASH included at the last byte of the signature
                 hashToSign = this.getHashForSigP2TR(toSignTx, encodedSignature[64]);
+                // And encodedSignature[0:64] holds the actual signature
                 signature = encodedSignature.subarray(0, -1);
             }
             else {
+                // Fail validation if the signature is not 64 or 65 bytes
                 throw new Error('Invalid Schnorr signature provided.');
             }
-            return ecc.verifySchnorr(hashToSign, publicKey, signature);
+            // Computing OP_CHECKSIG in Javascript
+            return bitcoinerlab_secp256k1_1.default.verifySchnorr(hashToSign, publicKey, signature);
         }
         else {
             throw new Error('Only P2WPKH, P2SH-P2WPKH, and single-key-spend P2TR BIP-322 verification is supported. Unsupported address is provided.');
         }
     }
+    /**
+     * Verify a legacy BIP-137 signature.
+     * Note that a signature is considered valid for all types of addresses that can be derived from the recovered public key.
+     * @param signerAddress Address of the signing address
+     * @param message message_challenge signed by the address
+     * @param signatureBase64 Signature produced by the signing address
+     * @returns True if the provided signature is a valid BIP-137 signature for the given message and address, false if otherwise
+     * @throws If the provided signature fails basic validation, or if unsupported address and signature are provided
+     */
     static verifyBIP137Signature(signerAddress, message, signatureBase64) {
-        if (Address.isP2PKH(signerAddress)) {
+        if (helpers_1.Address.isP2PKH(signerAddress)) {
             return bitcoinMessage.verify(message, signerAddress, signatureBase64);
         }
         else {
-            const publicKeySigned = BIP137.derivePubKey(message, signatureBase64);
-            const legacySigningAddress = Address.convertPubKeyIntoAddress(publicKeySigned, 'p2pkh').mainnet;
-            if (Address.isP2SH(signerAddress)) {
-                const p2shAddressDerived = Address.convertPubKeyIntoAddress(publicKeySigned, 'p2sh-p2wpkh');
+            // Recover the public key associated with the signature
+            const publicKeySigned = helpers_1.BIP137.derivePubKey(message, signatureBase64);
+            // Set the equivalent legacy address to prepare for validation from bitcoinjs-message
+            const legacySigningAddress = helpers_1.Address.convertPubKeyIntoAddress(publicKeySigned, 'p2pkh').mainnet;
+            // Make sure that public key recovered corresponds to the claimed signing address
+            if (helpers_1.Address.isP2SH(signerAddress)) {
+                // Assume it is a P2SH-P2WPKH address, derive a P2SH-P2WPKH address based on the public key recovered
+                const p2shAddressDerived = helpers_1.Address.convertPubKeyIntoAddress(publicKeySigned, 'p2sh-p2wpkh');
+                // Assert that the derived address is identical to the claimed signing address
                 if (p2shAddressDerived.mainnet !== signerAddress && p2shAddressDerived.testnet !== signerAddress) {
-                    return false;
+                    return false; // Derived address did not match with the claimed signing address
                 }
             }
-            else if (Address.isP2WPKH(signerAddress)) {
-                const p2wpkhAddressDerived = Address.convertPubKeyIntoAddress(publicKeySigned, 'p2wpkh');
+            else if (helpers_1.Address.isP2WPKH(signerAddress)) {
+                // Assume it is a P2WPKH address, derive a P2WPKH address based on the public key recovered
+                const p2wpkhAddressDerived = helpers_1.Address.convertPubKeyIntoAddress(publicKeySigned, 'p2wpkh');
+                // Assert that the derived address is identical to the claimed signing address
                 if (p2wpkhAddressDerived.mainnet !== signerAddress && p2wpkhAddressDerived.testnet !== signerAddress) {
-                    return false;
+                    return false; // Derived address did not match with the claimed signing address
                 }
             }
-            else if (Address.isP2TR(signerAddress)) {
-                const p2trAddressDerived = Address.convertPubKeyIntoAddress(publicKeySigned, 'p2tr');
+            else if (helpers_1.Address.isP2TR(signerAddress)) {
+                // Assume it is a P2TR address, derive a P2TR address based on the public key recovered
+                const p2trAddressDerived = helpers_1.Address.convertPubKeyIntoAddress(publicKeySigned, 'p2tr');
+                // Assert that the derived address is identical to the claimed signing address
                 if (p2trAddressDerived.mainnet !== signerAddress && p2trAddressDerived.testnet !== signerAddress) {
-                    return false;
+                    return false; // Derived address did not match with the claimed signing address
                 }
             }
             else {
-                return false;
+                return false; // Unsupported address type
             }
+            // Validate the signature using bitcoinjs-message if address assertion succeeded
             return bitcoinMessage.verify(message, legacySigningAddress, signatureBase64);
         }
     }
+    /**
+     * Compute the hash to be signed for a given P2WPKH BIP-322 toSign transaction.
+     * @param toSignTx PSBT instance of the toSign transaction
+     * @returns Computed transaction hash that requires signing
+     */
     static getHashForSigP2WPKH(toSignTx) {
+        // Create a signing script to unlock the P2WPKH output based on the P2PKH template
+        // Reference: https://github.com/bitcoinjs/bitcoinjs-lib/blob/1a9119b53bcea4b83a6aa8b948f0e6370209b1b4/ts_src/psbt.ts#L1654
         const signingScript = bitcoin.payments.p2pkh({
             hash: toSignTx.data.inputs[0].witnessUtxo.script.subarray(2)
         }).output;
+        // Return computed transaction hash to be signed 
         return toSignTx.extractTransaction().hashForWitnessV0(0, signingScript, 0, bitcoin.Transaction.SIGHASH_ALL);
     }
+    /**
+     * Compute the hash to be signed for a given P2SH-P2WPKH BIP-322 toSign transaction.
+     * @param toSignTx PSBT instance of the toSign transaction
+     * @param hashedPubkey Hashed public key of the signing address
+     * @returns Computed transaction hash that requires signing
+     */
     static getHashForSigP2SHInP2WPKH(toSignTx, hashedPubkey) {
+        // Create a signing script to unlock the P2WPKH output based on the P2PKH template
+        // Reference: https://github.com/bitcoinjs/bitcoinjs-lib/blob/1a9119b53bcea4b83a6aa8b948f0e6370209b1b4/ts_src/psbt.ts#L1654
+        // Like P2WPKH, the hash for deriving the meaningfulScript for a P2SH-P2WPKH transaction is its public key hash
+        // It can be derived by hashing the provided public key in the witness stack
         const signingScript = bitcoin.payments.p2pkh({
             hash: hashedPubkey
         }).output;
+        // Return computed transaction hash to be signed 
         return toSignTx.extractTransaction().hashForWitnessV0(0, signingScript, 0, bitcoin.Transaction.SIGHASH_ALL);
     }
+    /**
+     * Compute the hash to be signed for a given P2TR BIP-322 toSign transaction.
+     * @param toSignTx PSBT instance of the toSign transaction
+     * @param hashType Hash type used to sign the toSign transaction, must be either 0x00 or 0x01
+     * @returns Computed transaction hash that requires signing
+     * @throws Error if hashType is anything other than 0x00 or 0x01
+     */
     static getHashForSigP2TR(toSignTx, hashType) {
+        // BIP-322 states that 'all signatures must use the SIGHASH_ALL flag'
+        // But, in BIP-341, SIGHASH_DEFAULT (0x00) is equivalent to SIGHASH_ALL (0x01) so both should be allowed 
         if (hashType !== bitcoin.Transaction.SIGHASH_DEFAULT && hashType !== bitcoin.Transaction.SIGHASH_ALL) {
+            // Throw error if hashType is neither SIGHASH_DEFAULT or SIGHASH_ALL
             throw new Error('Invalid SIGHASH used in signature. Must be either SIGHASH_ALL or SIGHASH_DEFAULT.');
         }
+        // Return computed transaction hash to be signed
         return toSignTx.extractTransaction().hashForWitnessV1(0, [toSignTx.data.inputs[0].witnessUtxo.script], [0], hashType);
     }
 }
-export default Verifier;
+exports.default = Verifier;
 //# sourceMappingURL=Verifier.js.map

package/dist/bitcoinjs/DecodeScriptSignature.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 interface ScriptSignature {
     signature: Buffer;
     hashType: number;

package/dist/bitcoinjs/DecodeScriptSignature.js

@@ -1,4 +1,8 @@
-export function decodeScriptSignature(buffer) {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeScriptSignature = void 0;
+// Taken from https://github.com/bitcoinjs/bitcoinjs-lib/blob/5d2ff1c61165932e2814d5f37630e6720168561c/ts_src/script_signature.ts#L29
+function decodeScriptSignature(buffer) {
     const hashType = buffer.readUInt8(buffer.length - 1);
     const hashTypeMod = hashType & ~0x80;
     if (hashTypeMod <= 0 || hashTypeMod >= 4)
@@ -9,6 +13,7 @@ export function decodeScriptSignature(buffer) {
     const signature = Buffer.concat([r, s], 64);
     return { signature, hashType };
 }
+exports.decodeScriptSignature = decodeScriptSignature;
 function fromDER(x) {
     if (x[0] === 0x00)
         x = x.slice(1);
@@ -48,6 +53,7 @@ function decode2(buffer) {
         throw new Error('S value is negative');
     if (lenS > 1 && buffer[lenR + 6] === 0x00 && !(buffer[lenR + 7] & 0x80))
         throw new Error('S value excessively padded');
+    // non-BIP66 - extract R, S values
     return {
         r: buffer.slice(4, 4 + lenR),
         s: buffer.slice(6 + lenR),

package/dist/bitcoinjs/index.js

@@ -1,3 +1,6 @@
-import { decodeScriptSignature } from "./DecodeScriptSignature";
-export { decodeScriptSignature };
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeScriptSignature = void 0;
+const DecodeScriptSignature_1 = require("./DecodeScriptSignature");
+Object.defineProperty(exports, "decodeScriptSignature", { enumerable: true, get: function () { return DecodeScriptSignature_1.decodeScriptSignature; } });
 //# sourceMappingURL=index.js.map

package/dist/helpers/Address.d.ts

@@ -1,11 +1,58 @@
+/// <reference types="node" />
+/**
+ * Class that implement address-related utility functions.
+ */
 declare class Address {
+    /**
+     * Check if a given Bitcoin address is a pay-to-public-key-hash (p2pkh) address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address correspond to a valid P2PKH address, false if otherwise
+     */
     static isP2PKH(address: string): boolean;
+    /**
+     * Check if a given Bitcoin address is a pay-to-script-hash (P2SH) address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address correspond to a valid P2SH address, false if otherwise
+     */
     static isP2SH(address: string): boolean;
+    /**
+     * Check if a given Bitcoin address is a pay-to-witness-public-key-hash (P2WPKH) address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address correspond to a valid P2WPKH address, false if otherwise
+     */
     static isP2WPKH(address: string): boolean;
+    /**
+     * Check if a given Bitcoin address is a taproot address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address is a taproot address, false if otherwise
+     */
     static isP2TR(address: string): boolean;
+    /**
+     * Check if a given witness stack corresponds to a P2WPKH address.
+     * @param witness Witness data associated with the toSign BIP-322 transaction
+     * @returns True if the provided witness stack correspond to a valid P2WPKH address, false if otherwise
+     */
     static isP2WPKHWitness(witness: Buffer[]): boolean;
+    /**
+     * Check if a given witness stack corresponds to a single-key-spend P2TR address.
+     * @param witness Witness data associated with the toSign BIP-322 transaction
+     * @returns True if the provided address and witness stack correspond to a valid single-key-spend P2TR address, false if otherwise
+     */
     static isSingleKeyP2TRWitness(witness: Buffer[]): boolean;
+    /**
+     * Convert a given Bitcoin address into its corresponding script public key.
+     * Reference: https://github.com/buidl-bitcoin/buidl-python/blob/d79e9808e8ca60975d315be41293cb40d968626d/buidl/script.py#L607
+     * @param address Bitcoin address
+     * @returns Script public key of the given Bitcoin address
+     * @throws Error when the provided address is not a valid Bitcoin address
+     */
     static convertAdressToScriptPubkey(address: string): Buffer;
+    /**
+     * Convert a given public key into a corresponding Bitcoin address.
+     * @param publicKey Public key for deriving the address, or internal public key for deriving taproot address
+     * @param addressType Bitcoin address type to be derived, must be either 'p2pkh', 'p2sh-p2wpkh', 'p2wpkh', or 'p2tr'
+     * @returns Bitcoin address that correspond to the given public key in both mainnet and testnet
+     */
     static convertPubKeyIntoAddress(publicKey: Buffer, addressType: 'p2pkh' | 'p2sh-p2wpkh' | 'p2wpkh' | 'p2tr'): {
         mainnet: string;
         testnet: string;

package/dist/helpers/Address.js

@@ -1,44 +1,106 @@
-import * as bitcoin from '@exodus/bitcoinjs';
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Import dependency
+const bitcoin = __importStar(require("@exodus/bitcoinjs-lib"));
+/**
+ * Class that implement address-related utility functions.
+ */
 class Address {
+    /**
+     * Check if a given Bitcoin address is a pay-to-public-key-hash (p2pkh) address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address correspond to a valid P2PKH address, false if otherwise
+     */
     static isP2PKH(address) {
+        // Check if the provided address is a P2PKH address
         if (address[0] === '1' || address[0] === 'm' || address[0] === 'n') {
-            return true;
+            return true; // P2PKH address
         }
         else {
             return false;
         }
     }
+    /**
+     * Check if a given Bitcoin address is a pay-to-script-hash (P2SH) address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address correspond to a valid P2SH address, false if otherwise
+     */
     static isP2SH(address) {
+        // Check if the provided address is a P2SH address
         if (address[0] === '3' || address[0] === '2') {
-            return true;
+            return true; // P2SH address
         }
         else {
             return false;
         }
     }
+    /**
+     * Check if a given Bitcoin address is a pay-to-witness-public-key-hash (P2WPKH) address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address correspond to a valid P2WPKH address, false if otherwise
+     */
     static isP2WPKH(address) {
+        // Check if the provided address is a P2WPKH/P2WSH address
         if (address.slice(0, 4) === 'bc1q' || address.slice(0, 4) === 'tb1q') {
+            // Either a P2WPKH / P2WSH address
+            // Convert the address into a scriptPubKey
             const scriptPubKey = this.convertAdressToScriptPubkey(address);
+            // Check if the scriptPubKey is exactly 22 bytes since P2WPKH scriptPubKey should be 0014<20-BYTE-PUBKEY-HASH>
             if (scriptPubKey.byteLength === 22) {
-                return true;
+                return true; // P2WPKH
             }
             else {
-                return false;
+                return false; // Not P2WPKH, probably P2WSH
             }
         }
         else {
             return false;
         }
     }
+    /**
+     * Check if a given Bitcoin address is a taproot address.
+     * @param address Bitcoin address to be checked
+     * @returns True if the provided address is a taproot address, false if otherwise
+     */
     static isP2TR(address) {
         if (address.slice(0, 4) === 'bc1p' || address.slice(0, 4) === 'tb1p') {
-            return true;
+            return true; // P2TR address
         }
         else {
             return false;
         }
     }
+    /**
+     * Check if a given witness stack corresponds to a P2WPKH address.
+     * @param witness Witness data associated with the toSign BIP-322 transaction
+     * @returns True if the provided witness stack correspond to a valid P2WPKH address, false if otherwise
+     */
     static isP2WPKHWitness(witness) {
+        // Check whether the witness stack is as expected for a P2WPKH address
+        // It should contain exactly two items, with the second item being a public key with 33 bytes, and the first byte must be either 0x02/0x03
         if (witness.length === 2 && witness[1].byteLength === 33 && (witness[1][0] === 0x02 || witness[1][0] === 0x03)) {
             return true;
         }
@@ -46,7 +108,14 @@ class Address {
             return false;
         }
     }
+    /**
+     * Check if a given witness stack corresponds to a single-key-spend P2TR address.
+     * @param witness Witness data associated with the toSign BIP-322 transaction
+     * @returns True if the provided address and witness stack correspond to a valid single-key-spend P2TR address, false if otherwise
+     */
     static isSingleKeyP2TRWitness(witness) {
+        // Check whether the witness stack is as expected for a single-key-spend taproot address
+        // It should contain exactly one items which is the signature for the transaction
         if (witness.length === 1) {
             return true;
         }
@@ -54,27 +123,39 @@ class Address {
             return false;
         }
     }
+    /**
+     * Convert a given Bitcoin address into its corresponding script public key.
+     * Reference: https://github.com/buidl-bitcoin/buidl-python/blob/d79e9808e8ca60975d315be41293cb40d968626d/buidl/script.py#L607
+     * @param address Bitcoin address
+     * @returns Script public key of the given Bitcoin address
+     * @throws Error when the provided address is not a valid Bitcoin address
+     */
     static convertAdressToScriptPubkey(address) {
         if (address[0] === '1' || address[0] === 'm' || address[0] === 'n') {
+            // P2PKH address
             return bitcoin.payments.p2pkh({
                 address: address,
                 network: (address[0] === '1') ? bitcoin.networks.bitcoin : bitcoin.networks.testnet
             }).output;
         }
         else if (address[0] === '3' || address[0] === '2') {
+            // P2SH address
             return bitcoin.payments.p2sh({
                 address: address,
                 network: (address[0] === '3') ? bitcoin.networks.bitcoin : bitcoin.networks.testnet
             }).output;
         }
         else if (address.slice(0, 4) === 'bc1q' || address.slice(0, 4) === 'tb1q') {
+            // P2WPKH or P2WSH address
             if (address.length === 42) {
+                // P2WPKH address
                 return bitcoin.payments.p2wpkh({
                     address: address,
                     network: (address.slice(0, 4) === 'bc1q') ? bitcoin.networks.bitcoin : bitcoin.networks.testnet
                 }).output;
             }
             else if (address.length === 62) {
+                // P2WSH address
                 return bitcoin.payments.p2wsh({
                     address: address,
                     network: (address.slice(0, 4) === 'bc1q') ? bitcoin.networks.bitcoin : bitcoin.networks.testnet
@@ -83,6 +164,7 @@ class Address {
         }
         else if (address.slice(0, 4) === 'bc1p' || address.slice(0, 4) === 'tb1p') {
             if (address.length === 62) {
+                // P2TR address
                 return bitcoin.payments.p2tr({
                     address: address,
                     network: (address.slice(0, 4) === 'bc1p') ? bitcoin.networks.bitcoin : bitcoin.networks.testnet
@@ -91,6 +173,12 @@ class Address {
         }
         throw new Error("Unknown address type");
     }
+    /**
+     * Convert a given public key into a corresponding Bitcoin address.
+     * @param publicKey Public key for deriving the address, or internal public key for deriving taproot address
+     * @param addressType Bitcoin address type to be derived, must be either 'p2pkh', 'p2sh-p2wpkh', 'p2wpkh', or 'p2tr'
+     * @returns Bitcoin address that correspond to the given public key in both mainnet and testnet
+     */
     static convertPubKeyIntoAddress(publicKey, addressType) {
         switch (addressType) {
             case 'p2pkh':
@@ -99,6 +187,7 @@ class Address {
                     testnet: bitcoin.payments.p2pkh({ pubkey: publicKey, network: bitcoin.networks.testnet }).address
                 };
             case 'p2sh-p2wpkh':
+                // Reference: https://github.com/bitcoinjs/bitcoinjs-lib/blob/1a9119b53bcea4b83a6aa8b948f0e6370209b1b4/test/integration/addresses.spec.ts#L70
                 return {
                     mainnet: bitcoin.payments.p2sh({
                         redeem: bitcoin.payments.p2wpkh({ pubkey: publicKey, network: bitcoin.networks.bitcoin }),
@@ -115,6 +204,7 @@ class Address {
                     testnet: bitcoin.payments.p2wpkh({ pubkey: publicKey, network: bitcoin.networks.testnet }).address
                 };
             case 'p2tr':
+                // Convert full-length public key into internal public key if necessary
                 const internalPubkey = publicKey.byteLength === 33 ? publicKey.subarray(1, 33) : publicKey;
                 return {
                     mainnet: bitcoin.payments.p2tr({ internalPubkey: internalPubkey, network: bitcoin.networks.bitcoin }).address,
@@ -125,5 +215,5 @@ class Address {
         }
     }
 }
-export default Address;
+exports.default = Address;
 //# sourceMappingURL=Address.js.map

package/dist/helpers/BIP137.d.ts

@@ -1,6 +1,27 @@
+/// <reference types="node" />
+/**
+ * Class that implement BIP137-related utility functions.
+ */
 declare class BIP137 {
+    /**
+     * Check if a given signature satisified the format of a BIP-137 signature.
+     * @param signature Base64-encoded signature to be checked
+     * @returns True if the provided signature correspond to a valid BIP-137 signature, false if otherwise
+     */
     static isBIP137Signature(signature: string): boolean;
+    /**
+     * Derive the public key that signed a valid BIP-137 signature.
+     * @param message Message signed by the signature
+     * @param signature Base-64 encoded signature to be decoded
+     * @returns Public key that signs the provided signature
+     */
     static derivePubKey(message: string, signature: string): Buffer;
+    /**
+     * Decode a BIP-137 signature.
+     * Function copied from bitcoinjs-message library.
+     * @param signature BIP-137 signature to be decoded
+     * @returns Decoded BIP-137 signature
+     */
     private static decodeSignature;
 }
 export default BIP137;