Merge branch 'master' into feat/hybrid

Author: Nesopie

.github/workflows/main_ci.yml

@@ -21,7 +21,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [14, 'lts/*']
+        node-version: [18, 'lts/*']
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     steps:
       - uses: actions/checkout@ec3a7ce113134d7a93b817d10a8272cb61118579 # v2
@@ -38,7 +38,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [14, 'lts/*']
+        node-version: [18, 'lts/*']
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     services:
       regtest:
@@ -61,17 +61,6 @@ jobs:
   #####################
   # Jobs without matrix
   #####################
-  audit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@ec3a7ce113134d7a93b817d10a8272cb61118579 # v2
-      - uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3
-        with:
-          node-version: 'lts/*'
-          registry-url: https://registry.npmjs.org/
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run audit
   coverage:
     runs-on: ubuntu-latest
     steps:

src/cjs/address.cjs

@@ -73,6 +73,13 @@ const FUTURE_SEGWIT_VERSION_WARNING =
   'End users MUST be warned carefully in the GUI and asked if they wish to proceed ' +
   'with caution. Wallets should verify the segwit version from the output of fromBech32, ' +
   'then decide when it is safe to use which version of segwit.';
+/**
+ * Converts an output buffer to a future segwit address.
+ * @param output - The output buffer.
+ * @param network - The network object.
+ * @returns The future segwit address.
+ * @throws {TypeError} If the program length or version is invalid for segwit address.
+ */
 function _toFutureSegwitAddress(output, network) {
   const data = output.slice(2);
   if (
@@ -92,7 +99,11 @@ function _toFutureSegwitAddress(output, network) {
   return toBech32(data, version, network.bech32);
 }
 /**
- * decode address with base58 specification,  return address version and address hash if valid
+ * Decodes a base58check encoded Bitcoin address and returns the version and hash.
+ *
+ * @param address - The base58check encoded Bitcoin address to decode.
+ * @returns An object containing the version and hash of the decoded address.
+ * @throws {TypeError} If the address is too short or too long.
  */
 function fromBase58Check(address) {
   const payload = bs58check_1.default.decode(address);
@@ -104,7 +115,10 @@ function fromBase58Check(address) {
   return { version, hash };
 }
 /**
- * decode address with bech32 specification,  return address version、address prefix and address data if valid
+ * Converts a Bech32 or Bech32m encoded address to its corresponding data representation.
+ * @param address - The Bech32 or Bech32m encoded address.
+ * @returns An object containing the version, prefix, and data of the address.
+ * @throws {TypeError} If the address uses the wrong encoding.
  */
 function fromBech32(address) {
   let result;
@@ -128,7 +142,10 @@ function fromBech32(address) {
   };
 }
 /**
- * encode address hash to base58 address with version
+ * Converts a hash to a Base58Check-encoded string.
+ * @param hash - The hash to be encoded.
+ * @param version - The version byte to be prepended to the encoded string.
+ * @returns The Base58Check-encoded string.
  */
 function toBase58Check(hash, version) {
   v.parse(v.tuple([types_js_1.Hash160bitSchema, types_js_1.UInt8Schema]), [
@@ -141,7 +158,11 @@ function toBase58Check(hash, version) {
   return bs58check_1.default.encode(payload);
 }
 /**
- * encode address hash to bech32 address with version and prefix
+ * Converts a buffer to a Bech32 or Bech32m encoded string.
+ * @param data - The buffer to be encoded.
+ * @param version - The version number to be used in the encoding.
+ * @param prefix - The prefix string to be used in the encoding.
+ * @returns The Bech32 or Bech32m encoded string.
  */
 function toBech32(data, version, prefix) {
   const words = bech32_1.bech32.toWords(data);
@@ -151,7 +172,11 @@ function toBech32(data, version, prefix) {
     : bech32_1.bech32m.encode(prefix, words);
 }
 /**
- * decode address from output script with network, return address if matched
+ * Converts an output script to a Bitcoin address.
+ * @param output - The output script as a Buffer.
+ * @param network - The Bitcoin network (optional).
+ * @returns The Bitcoin address corresponding to the output script.
+ * @throws If the output script has no matching address.
  */
 function fromOutputScript(output, network) {
   // TODO: Network
@@ -177,7 +202,11 @@ function fromOutputScript(output, network) {
   throw new Error(bscript.toASM(output) + ' has no matching Address');
 }
 /**
- * encodes address to output script with network, return output script if address matched
+ * Converts a Bitcoin address to its corresponding output script.
+ * @param address - The Bitcoin address to convert.
+ * @param network - The Bitcoin network to use. Defaults to the Bitcoin network.
+ * @returns The corresponding output script as a Buffer.
+ * @throws If the address has an invalid prefix or no matching script.
  */
 function toOutputScript(address, network) {
   network = network || networks.bitcoin;

src/cjs/address.d.ts

@@ -25,26 +25,48 @@ export interface Bech32Result {
     data: Uint8Array;
 }
 /**
- * decode address with base58 specification,  return address version and address hash if valid
+ * Decodes a base58check encoded Bitcoin address and returns the version and hash.
+ *
+ * @param address - The base58check encoded Bitcoin address to decode.
+ * @returns An object containing the version and hash of the decoded address.
+ * @throws {TypeError} If the address is too short or too long.
  */
 export declare function fromBase58Check(address: string): Base58CheckResult;
 /**
- * decode address with bech32 specification,  return address version、address prefix and address data if valid
+ * Converts a Bech32 or Bech32m encoded address to its corresponding data representation.
+ * @param address - The Bech32 or Bech32m encoded address.
+ * @returns An object containing the version, prefix, and data of the address.
+ * @throws {TypeError} If the address uses the wrong encoding.
  */
 export declare function fromBech32(address: string): Bech32Result;
 /**
- * encode address hash to base58 address with version
+ * Converts a hash to a Base58Check-encoded string.
+ * @param hash - The hash to be encoded.
+ * @param version - The version byte to be prepended to the encoded string.
+ * @returns The Base58Check-encoded string.
  */
 export declare function toBase58Check(hash: Uint8Array, version: number): string;
 /**
- * encode address hash to bech32 address with version and prefix
+ * Converts a buffer to a Bech32 or Bech32m encoded string.
+ * @param data - The buffer to be encoded.
+ * @param version - The version number to be used in the encoding.
+ * @param prefix - The prefix string to be used in the encoding.
+ * @returns The Bech32 or Bech32m encoded string.
  */
 export declare function toBech32(data: Uint8Array, version: number, prefix: string): string;
 /**
- * decode address from output script with network, return address if matched
+ * Converts an output script to a Bitcoin address.
+ * @param output - The output script as a Buffer.
+ * @param network - The Bitcoin network (optional).
+ * @returns The Bitcoin address corresponding to the output script.
+ * @throws If the output script has no matching address.
  */
 export declare function fromOutputScript(output: Uint8Array, network?: Network): string;
 /**
- * encodes address to output script with network, return output script if address matched
+ * Converts a Bitcoin address to its corresponding output script.
+ * @param address - The Bitcoin address to convert.
+ * @param network - The Bitcoin network to use. Defaults to the Bitcoin network.
+ * @returns The corresponding output script as a Buffer.
+ * @throws If the address has an invalid prefix or no matching script.
  */
 export declare function toOutputScript(address: string, network?: Network): Uint8Array;

src/cjs/bip66.cjs

@@ -6,6 +6,12 @@ Object.defineProperty(exports, '__esModule', { value: true });
 exports.check = check;
 exports.decode = decode;
 exports.encode = encode;
+/**
+ * Checks if the given buffer is a valid BIP66-encoded signature.
+ *
+ * @param buffer - The buffer to check.
+ * @returns A boolean indicating whether the buffer is a valid BIP66-encoded signature.
+ */
 function check(buffer) {
   if (buffer.length < 8) return false;
   if (buffer.length > 72) return false;
@@ -26,6 +32,14 @@ function check(buffer) {
     return false;
   return true;
 }
+/**
+ * Decodes a DER-encoded signature buffer and returns the R and S values.
+ * @param buffer - The DER-encoded signature buffer.
+ * @returns An object containing the R and S values.
+ * @throws {Error} If the DER sequence length is too short, too long, or invalid.
+ * @throws {Error} If the R or S length is zero or invalid.
+ * @throws {Error} If the R or S value is negative or excessively padded.
+ */
 function decode(buffer) {
   if (buffer.length < 8) throw new Error('DER sequence length is too short');
   if (buffer.length > 72) throw new Error('DER sequence length is too long');

src/cjs/bip66.d.ts

@@ -1,4 +1,18 @@
+/**
+ * Checks if the given buffer is a valid BIP66-encoded signature.
+ *
+ * @param buffer - The buffer to check.
+ * @returns A boolean indicating whether the buffer is a valid BIP66-encoded signature.
+ */
 export declare function check(buffer: Uint8Array): boolean;
+/**
+ * Decodes a DER-encoded signature buffer and returns the R and S values.
+ * @param buffer - The DER-encoded signature buffer.
+ * @returns An object containing the R and S values.
+ * @throws {Error} If the DER sequence length is too short, too long, or invalid.
+ * @throws {Error} If the R or S length is zero or invalid.
+ * @throws {Error} If the R or S value is negative or excessively padded.
+ */
 export declare function decode(buffer: Uint8Array): {
     r: Uint8Array;
     s: Uint8Array;

src/cjs/payments/bip341.cjs

@@ -119,19 +119,39 @@ function findScriptPath(node, hash) {
   }
   return undefined;
 }
+/**
+ * Calculates the tapleaf hash for a given Tapleaf object.
+ * @param leaf - The Tapleaf object to calculate the hash for.
+ * @returns The tapleaf hash as a Buffer.
+ */
 function tapleafHash(leaf) {
   const version = leaf.version || exports.LEAF_VERSION_TAPSCRIPT;
   return bcrypto.taggedHash(
     'TapLeaf',
     tools.concat([Uint8Array.from([version]), serializeScript(leaf.output)]),
   );
 }
+/**
+ * Computes the taproot tweak hash for a given public key and optional hash.
+ * If a hash is provided, the public key and hash are concatenated before computing the hash.
+ * If no hash is provided, only the public key is used to compute the hash.
+ *
+ * @param pubKey - The public key buffer.
+ * @param h - The optional hash buffer.
+ * @returns The taproot tweak hash.
+ */
 function tapTweakHash(pubKey, h) {
   return bcrypto.taggedHash(
     'TapTweak',
     tools.concat(h ? [pubKey, h] : [pubKey]),
   );
 }
+/**
+ * Tweak a public key with a given tweak hash.
+ * @param pubKey - The public key to be tweaked.
+ * @param h - The tweak hash.
+ * @returns The tweaked public key or null if the input is invalid.
+ */
 function tweakKey(pubKey, h) {
   if (!(pubKey instanceof Uint8Array)) return null;
   if (pubKey.length !== 32) return null;
@@ -147,9 +167,22 @@ function tweakKey(pubKey, h) {
     x: Uint8Array.from(res.xOnlyPubkey),
   };
 }
+/**
+ * Computes the TapBranch hash by concatenating two buffers and applying the 'TapBranch' tagged hash algorithm.
+ *
+ * @param a - The first buffer.
+ * @param b - The second buffer.
+ * @returns The TapBranch hash of the concatenated buffers.
+ */
 function tapBranchHash(a, b) {
   return bcrypto.taggedHash('TapBranch', tools.concat([a, b]));
 }
+/**
+ * Serializes a script by encoding its length as a varint and concatenating it with the script.
+ *
+ * @param s - The script to be serialized.
+ * @returns The serialized script as a Buffer.
+ */
 function serializeScript(s) {
   /* global BigInt */
   const varintLen = bufferutils_js_1.varuint.encodingLength(s.length);

src/cjs/payments/bip341.d.ts

@@ -42,7 +42,27 @@ export declare function toHashTree(scriptTree: Taptree): HashTree;
  * path is found
  */
 export declare function findScriptPath(node: HashTree, hash: Uint8Array): Uint8Array[] | undefined;
+/**
+ * Calculates the tapleaf hash for a given Tapleaf object.
+ * @param leaf - The Tapleaf object to calculate the hash for.
+ * @returns The tapleaf hash as a Buffer.
+ */
 export declare function tapleafHash(leaf: Tapleaf): Uint8Array;
+/**
+ * Computes the taproot tweak hash for a given public key and optional hash.
+ * If a hash is provided, the public key and hash are concatenated before computing the hash.
+ * If no hash is provided, only the public key is used to compute the hash.
+ *
+ * @param pubKey - The public key buffer.
+ * @param h - The optional hash buffer.
+ * @returns The taproot tweak hash.
+ */
 export declare function tapTweakHash(pubKey: Uint8Array, h: Uint8Array | undefined): Uint8Array;
+/**
+ * Tweak a public key with a given tweak hash.
+ * @param pubKey - The public key to be tweaked.
+ * @param h - The tweak hash.
+ * @returns The tweaked public key or null if the input is invalid.
+ */
 export declare function tweakKey(pubKey: Uint8Array, h: Uint8Array | undefined): TweakedPublicKey | null;
 export {};