Merge pull request #2142 from typeofYh/master

docs: Completion and optimization annotation

Author: junderw

src/address.d.ts

@@ -26,26 +26,48 @@ export interface Bech32Result {
     data: Buffer;
 }
 /**
- * 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: Buffer, 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: Buffer, 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: Buffer, 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): Buffer;

src/address.js

@@ -23,6 +23,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 (
@@ -42,7 +49,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 = Buffer.from(bs58check.decode(address));
@@ -55,7 +66,10 @@ function fromBase58Check(address) {
 }
 exports.fromBase58Check = fromBase58Check;
 /**
- * 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;
@@ -80,7 +94,10 @@ function fromBech32(address) {
 }
 exports.fromBech32 = fromBech32;
 /**
- * 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) {
   (0, types_1.typeforce)(
@@ -94,7 +111,11 @@ function toBase58Check(hash, version) {
 }
 exports.toBase58Check = toBase58Check;
 /**
- * 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);
@@ -105,7 +126,11 @@ function toBech32(data, version, prefix) {
 }
 exports.toBech32 = toBech32;
 /**
- * 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
@@ -132,7 +157,11 @@ function fromOutputScript(output, network) {
 }
 exports.fromOutputScript = fromOutputScript;
 /**
- * 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/bip66.d.ts

@@ -1,5 +1,19 @@
 /// <reference types="node" />
+/**
+ * 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: Buffer): 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: Buffer): {
     r: Buffer;
     s: Buffer;

src/bip66.js

@@ -4,6 +4,12 @@
 // NOTE: SIGHASH byte ignored AND restricted, truncate before use
 Object.defineProperty(exports, '__esModule', { value: true });
 exports.encode = exports.decode = exports.check = void 0;
+/**
+ * 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;
@@ -25,6 +31,14 @@ function check(buffer) {
   return true;
 }
 exports.check = check;
+/**
+ * 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/payments/bip341.d.ts

@@ -43,7 +43,27 @@ export declare function toHashTree(scriptTree: Taptree): HashTree;
  * path is found
  */
 export declare function findScriptPath(node: HashTree, hash: Buffer): Buffer[] | 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): Buffer;
+/**
+ * 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: Buffer, h: Buffer | undefined): Buffer;
+/**
+ * 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: Buffer, h: Buffer | undefined): TweakedPublicKey | null;
 export {};

src/payments/bip341.js

@@ -79,6 +79,11 @@ function findScriptPath(node, hash) {
   return undefined;
 }
 exports.findScriptPath = findScriptPath;
+/**
+ * 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(
@@ -90,13 +95,28 @@ function tapleafHash(leaf) {
   );
 }
 exports.tapleafHash = tapleafHash;
+/**
+ * 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',
     buffer_1.Buffer.concat(h ? [pubKey, h] : [pubKey]),
   );
 }
 exports.tapTweakHash = tapTweakHash;
+/**
+ * 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 (!buffer_1.Buffer.isBuffer(pubKey)) return null;
   if (pubKey.length !== 32) return null;
@@ -110,9 +130,22 @@ function tweakKey(pubKey, h) {
   };
 }
 exports.tweakKey = tweakKey;
+/**
+ * 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', buffer_1.Buffer.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) {
   const varintLen = bufferutils_1.varuint.encodingLength(s.length);
   const buffer = buffer_1.Buffer.allocUnsafe(varintLen); // better

ts_src/address.ts

@@ -44,6 +44,13 @@ const FUTURE_SEGWIT_VERSION_WARNING: string =
   '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: Buffer, network: Network): string {
   const data = output.slice(2);
 
@@ -70,7 +77,11 @@ function _toFutureSegwitAddress(output: Buffer, network: Network): string {
 }
 
 /**
- * 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 function fromBase58Check(address: string): Base58CheckResult {
   const payload = Buffer.from(bs58check.decode(address));
@@ -86,7 +97,10 @@ export 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 function fromBech32(address: string): Bech32Result {
   let result;
@@ -114,7 +128,10 @@ export 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 function toBase58Check(hash: Buffer, version: number): string {
   typeforce(tuple(Hash160bit, UInt8), arguments);
@@ -127,7 +144,11 @@ export function toBase58Check(hash: Buffer, 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 function toBech32(
   data: Buffer,
@@ -143,7 +164,11 @@ export function toBech32(
 }
 
 /**
- * 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 function fromOutputScript(output: Buffer, network?: Network): string {
   // TODO: Network
@@ -172,7 +197,11 @@ export function fromOutputScript(output: Buffer, 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 function toOutputScript(address: string, network?: Network): Buffer {
   network = network || networks.bitcoin;