Merge pull request #2188 from SpiderMan670/master

doc: improve document of crypto
bitcoinjs · Dec 12, 2024 · ec1f51c · ec1f51c
2 parents 68ed198 + 2c3c662
commit ec1f51c
Show file tree

Hide file tree

Showing 4 changed files with 137 additions and 8 deletions.
diff --git a/src/cjs/crypto.cjs b/src/cjs/crypto.cjs
@@ -57,9 +57,21 @@ exports.taggedHash = taggedHash;
 const ripemd160_1 = require('@noble/hashes/ripemd160');
 const sha256_1 = require('@noble/hashes/sha256');
 const tools = __importStar(require('uint8array-tools'));
+/**
+ * Computes the HASH160 (RIPEMD-160 after SHA-256) of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The HASH160 of the input buffer.
+ */
 function hash160(buffer) {
   return (0, ripemd160_1.ripemd160)((0, sha256_1.sha256)(buffer));
 }
+/**
+ * Computes the double SHA-256 hash of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The double SHA-256 hash of the input buffer.
+ */
 function hash256(buffer) {
   return (0, sha256_1.sha256)((0, sha256_1.sha256)(buffer));
 }
@@ -74,9 +86,22 @@ exports.TAGS = [
   'KeyAgg list',
   'KeyAgg coefficient',
 ];
-/** An object mapping tags to their tagged hash prefix of [SHA256(tag) | SHA256(tag)] */
 /**
- * Defines the tagged hash prefixes used in the crypto module.
+ * A collection of tagged hash prefixes used in various BIP (Bitcoin Improvement Proposals)
+ * and Taproot-related operations. Each prefix is represented as a `Uint8Array`.
+ *
+ * @constant
+ * @type {TaggedHashPrefixes}
+ *
+ * @property {'BIP0340/challenge'} - Prefix for BIP0340 challenge.
+ * @property {'BIP0340/aux'} - Prefix for BIP0340 auxiliary data.
+ * @property {'BIP0340/nonce'} - Prefix for BIP0340 nonce.
+ * @property {TapLeaf} - Prefix for Taproot leaf.
+ * @property {TapBranch} - Prefix for Taproot branch.
+ * @property {TapSighash} - Prefix for Taproot sighash.
+ * @property {TapTweak} - Prefix for Taproot tweak.
+ * @property {'KeyAgg list'} - Prefix for key aggregation list.
+ * @property {'KeyAgg coefficient'} - Prefix for key aggregation coefficient.
  */
 exports.TAGGED_HASH_PREFIXES = {
   'BIP0340/challenge': Uint8Array.from([
@@ -134,6 +159,13 @@ exports.TAGGED_HASH_PREFIXES = {
     78, 214, 66, 114, 129, 192, 145, 0, 249, 77, 205, 82, 201, 129,
   ]),
 };
+/**
+ * Computes a tagged hash using the specified prefix and data.
+ *
+ * @param prefix - The prefix to use for the tagged hash. This should be one of the values from the `TaggedHashPrefix` enum.
+ * @param data - The data to hash, provided as a `Uint8Array`.
+ * @returns The resulting tagged hash as a `Uint8Array`.
+ */
 function taggedHash(prefix, data) {
   return (0, sha256_1.sha256)(
     tools.concat([exports.TAGGED_HASH_PREFIXES[prefix], data]),

diff --git a/src/cjs/crypto.d.ts b/src/cjs/crypto.d.ts
@@ -1,14 +1,46 @@
+/**
+ * Computes the HASH160 (RIPEMD-160 after SHA-256) of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The HASH160 of the input buffer.
+ */
 export declare function hash160(buffer: Uint8Array): Uint8Array;
+/**
+ * Computes the double SHA-256 hash of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The double SHA-256 hash of the input buffer.
+ */
 export declare function hash256(buffer: Uint8Array): Uint8Array;
 export declare const TAGS: readonly ["BIP0340/challenge", "BIP0340/aux", "BIP0340/nonce", "TapLeaf", "TapBranch", "TapSighash", "TapTweak", "KeyAgg list", "KeyAgg coefficient"];
 export type TaggedHashPrefix = (typeof TAGS)[number];
 type TaggedHashPrefixes = {
     [key in TaggedHashPrefix]: Uint8Array;
 };
-/** An object mapping tags to their tagged hash prefix of [SHA256(tag) | SHA256(tag)] */
 /**
- * Defines the tagged hash prefixes used in the crypto module.
+ * A collection of tagged hash prefixes used in various BIP (Bitcoin Improvement Proposals)
+ * and Taproot-related operations. Each prefix is represented as a `Uint8Array`.
+ *
+ * @constant
+ * @type {TaggedHashPrefixes}
+ *
+ * @property {'BIP0340/challenge'} - Prefix for BIP0340 challenge.
+ * @property {'BIP0340/aux'} - Prefix for BIP0340 auxiliary data.
+ * @property {'BIP0340/nonce'} - Prefix for BIP0340 nonce.
+ * @property {TapLeaf} - Prefix for Taproot leaf.
+ * @property {TapBranch} - Prefix for Taproot branch.
+ * @property {TapSighash} - Prefix for Taproot sighash.
+ * @property {TapTweak} - Prefix for Taproot tweak.
+ * @property {'KeyAgg list'} - Prefix for key aggregation list.
+ * @property {'KeyAgg coefficient'} - Prefix for key aggregation coefficient.
  */
 export declare const TAGGED_HASH_PREFIXES: TaggedHashPrefixes;
+/**
+ * Computes a tagged hash using the specified prefix and data.
+ *
+ * @param prefix - The prefix to use for the tagged hash. This should be one of the values from the `TaggedHashPrefix` enum.
+ * @param data - The data to hash, provided as a `Uint8Array`.
+ * @returns The resulting tagged hash as a `Uint8Array`.
+ */
 export declare function taggedHash(prefix: TaggedHashPrefix, data: Uint8Array): Uint8Array;
 export {};
diff --git a/src/esm/crypto.js b/src/esm/crypto.js
@@ -7,9 +7,21 @@
 import { ripemd160 } from '@noble/hashes/ripemd160';
 import { sha256 } from '@noble/hashes/sha256';
 import * as tools from 'uint8array-tools';
+/**
+ * Computes the HASH160 (RIPEMD-160 after SHA-256) of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The HASH160 of the input buffer.
+ */
 export function hash160(buffer) {
   return ripemd160(sha256(buffer));
 }
+/**
+ * Computes the double SHA-256 hash of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The double SHA-256 hash of the input buffer.
+ */
 export function hash256(buffer) {
   return sha256(sha256(buffer));
 }
@@ -24,9 +36,22 @@ export const TAGS = [
   'KeyAgg list',
   'KeyAgg coefficient',
 ];
-/** An object mapping tags to their tagged hash prefix of [SHA256(tag) | SHA256(tag)] */
 /**
- * Defines the tagged hash prefixes used in the crypto module.
+ * A collection of tagged hash prefixes used in various BIP (Bitcoin Improvement Proposals)
+ * and Taproot-related operations. Each prefix is represented as a `Uint8Array`.
+ *
+ * @constant
+ * @type {TaggedHashPrefixes}
+ *
+ * @property {'BIP0340/challenge'} - Prefix for BIP0340 challenge.
+ * @property {'BIP0340/aux'} - Prefix for BIP0340 auxiliary data.
+ * @property {'BIP0340/nonce'} - Prefix for BIP0340 nonce.
+ * @property {TapLeaf} - Prefix for Taproot leaf.
+ * @property {TapBranch} - Prefix for Taproot branch.
+ * @property {TapSighash} - Prefix for Taproot sighash.
+ * @property {TapTweak} - Prefix for Taproot tweak.
+ * @property {'KeyAgg list'} - Prefix for key aggregation list.
+ * @property {'KeyAgg coefficient'} - Prefix for key aggregation coefficient.
  */
 export const TAGGED_HASH_PREFIXES = {
   'BIP0340/challenge': Uint8Array.from([
@@ -84,6 +109,13 @@ export const TAGGED_HASH_PREFIXES = {
     78, 214, 66, 114, 129, 192, 145, 0, 249, 77, 205, 82, 201, 129,
   ]),
 };
+/**
+ * Computes a tagged hash using the specified prefix and data.
+ *
+ * @param prefix - The prefix to use for the tagged hash. This should be one of the values from the `TaggedHashPrefix` enum.
+ * @param data - The data to hash, provided as a `Uint8Array`.
+ * @returns The resulting tagged hash as a `Uint8Array`.
+ */
 export function taggedHash(prefix, data) {
   return sha256(tools.concat([TAGGED_HASH_PREFIXES[prefix], data]));
 }
diff --git a/ts_src/crypto.ts b/ts_src/crypto.ts
@@ -8,10 +8,22 @@ import { ripemd160 } from '@noble/hashes/ripemd160';
 import { sha256 } from '@noble/hashes/sha256';
 import * as tools from 'uint8array-tools';
 
+/**
+ * Computes the HASH160 (RIPEMD-160 after SHA-256) of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The HASH160 of the input buffer.
+ */
 export function hash160(buffer: Uint8Array): Uint8Array {
   return ripemd160(sha256(buffer));
 }
 
+/**
+ * Computes the double SHA-256 hash of the given buffer.
+ *
+ * @param buffer - The input data to be hashed.
+ * @returns The double SHA-256 hash of the input buffer.
+ */
 export function hash256(buffer: Uint8Array): Uint8Array {
   return sha256(sha256(buffer));
 }
@@ -31,9 +43,23 @@ export type TaggedHashPrefix = (typeof TAGS)[number];
 type TaggedHashPrefixes = {
   [key in TaggedHashPrefix]: Uint8Array;
 };
-/** An object mapping tags to their tagged hash prefix of [SHA256(tag) | SHA256(tag)] */
+
 /**
- * Defines the tagged hash prefixes used in the crypto module.
+ * A collection of tagged hash prefixes used in various BIP (Bitcoin Improvement Proposals)
+ * and Taproot-related operations. Each prefix is represented as a `Uint8Array`.
+ *
+ * @constant
+ * @type {TaggedHashPrefixes}
+ *
+ * @property {'BIP0340/challenge'} - Prefix for BIP0340 challenge.
+ * @property {'BIP0340/aux'} - Prefix for BIP0340 auxiliary data.
+ * @property {'BIP0340/nonce'} - Prefix for BIP0340 nonce.
+ * @property {TapLeaf} - Prefix for Taproot leaf.
+ * @property {TapBranch} - Prefix for Taproot branch.
+ * @property {TapSighash} - Prefix for Taproot sighash.
+ * @property {TapTweak} - Prefix for Taproot tweak.
+ * @property {'KeyAgg list'} - Prefix for key aggregation list.
+ * @property {'KeyAgg coefficient'} - Prefix for key aggregation coefficient.
  */
 export const TAGGED_HASH_PREFIXES: TaggedHashPrefixes = {
   'BIP0340/challenge': Uint8Array.from([
@@ -92,6 +118,13 @@ export const TAGGED_HASH_PREFIXES: TaggedHashPrefixes = {
   ]),
 };
 
+/**
+ * Computes a tagged hash using the specified prefix and data.
+ *
+ * @param prefix - The prefix to use for the tagged hash. This should be one of the values from the `TaggedHashPrefix` enum.
+ * @param data - The data to hash, provided as a `Uint8Array`.
+ * @returns The resulting tagged hash as a `Uint8Array`.
+ */
 export function taggedHash(
   prefix: TaggedHashPrefix,
   data: Uint8Array,