📄 docs: add other docs and build src

Author: jasonandjay

src/address.d.ts

@@ -2,7 +2,7 @@
 /**
  * bitcoin address decode and encode tools, include base58、bech32 and output script
  *
- * networks support bitcoin、litecoin、bitcoin testnet、litecoin testnet、bitcoin regtest、litecoin regtest and so on
+ * networks support bitcoin、bitcoin testnet and bitcoin regtest
  *
  * addresses support P2PKH、P2SH、P2WPKH、P2WSH、P2TR and so on
  *
@@ -27,137 +27,25 @@ export interface Bech32Result {
 }
 /**
  * decode address with base58 specification,  return address version and address hash if valid
- * @case
- * ```ts
- * // You can test it here and find more case in test/address.spec.ts
- * const result = address.fromBase58Check('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH')
- * console.log(JSON.stringify(result))
- * // => {"version":0,"hash":{"type":"Buffer","data":[117,30,118,232,25,145,150,212,84,148,28,69,209,179,163,35,241,67,59,214]}}
- * ```
  */
 export declare function fromBase58Check(address: string): Base58CheckResult;
 /**
  * decode address with bech32 specification,  return address version、address prefix and address data if valid
- * @example
- * ```ts
- * // valid case
- * fromBech32('BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4')
- * // => {version: 0, prefix: 'bc', data: <Buffer 75 1e 76 e8 19 91 96 d4 54 94 1c 45 d1 b3 a3 23 f1 43 3b d6>}
- *
- * // invalid case
- * fromBase58Check('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5')
- * // => Invalid checksum
- *
- * // invalid case
- * fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sL5k7')
- * // => Mixed-case string
- *
- * // invalid case
- * fromBase58Check('tb1pw508d6qejxtdg4y5r3zarquvzkan')
- * // => Excess padding
- *
- * // invalid case
- * fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
- * // => Excess padding
- *
- * // invalid case
- * fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
- * // => Non-zero padding
- *
- * // invalid case
- * fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3pjxtptv')
- * // => uses wrong encoding
- *
- * // invalid case
- * fromBase58Check('bc1p0xlxvlhemja6c4dqv22uapctqupfhlxm9h8z3k2e72q4k9hcz7vqh2y7hd')
- * // => uses wrong encoding
- * ```
  */
 export declare function fromBech32(address: string): Bech32Result;
 /**
  * encode address hash to base58 address with version
- *
- * @example
- * ```ts
- * // valid case
- * toBase58Check('751e76e8199196d454941c45d1b3a323f1433bd6', 0)
- * // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
- * ```
  */
 export declare function toBase58Check(hash: Buffer, version: number): string;
 /**
  * encode address hash to bech32 address with version and prefix
- *
- * @example
- * ```ts
- * // valid case
- * toBech32('000000c4a5cad46221b2a187905e5266362b99d5e91c6ce24d165dab93e86433', 0, 'tb)
- * // => tb1qqqqqp399et2xygdj5xreqhjjvcmzhxw4aywxecjdzew6hylgvsesrxh6hy
- * ```
  */
 export declare function toBech32(data: Buffer, version: number, prefix: string): string;
 /**
  * decode address from output script with network, return address if matched
- * @example
- * ```ts
- * // valid case
- * fromOutputScript('OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG', 'bicoin)
- * // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
- *
- * // invalid case
- * fromOutputScript('031f1e68f82112b373f0fe980b3a89d212d2b5c01fb51eb25acb8b4c4b4299ce95 OP_CHECKSIG', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_TRUE 032487c2a32f7c8d57d2a93906a6457afd00697925b0e6e145d89af6d3bca33016 02308673d16987eaa010e540901cc6fe3695e758c19f46ce604e174dac315e685a OP_2 OP_CHECKMULTISIG', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_RETURN 06deadbeef03f895a2ad89fb6d696497af486cb7c644a27aa568c7a18dd06113401115185474', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_0 75', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_0 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_1 75', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_1 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_1 fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f', undefined)
- * // => 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
- * @example
- * ```ts
- * // valid case
- * toOutputScript('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH', 'bicoin)
- * // => OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG
- *
- * // invalid case
- * toOutputScript('24kPZCmVgzfkpGdXExy56234MRHrsqQxNWE', undefined)
- * // => has no matching Script
- *
- * // invalid case
- * toOutputScript('BC1SW50QGDZ25J', { "bech32": "foo" })
- * // => has an invalid prefix
- *
- * // invalid case
- * toOutputScript('bc1rw5uspcuh', undefined)
- * // => has no matching Script
- * ```
  */
 export declare function toOutputScript(address: string, network?: Network): Buffer;

src/address.js

@@ -43,13 +43,6 @@ function _toFutureSegwitAddress(output, network) {
 }
 /**
  * decode address with base58 specification,  return address version and address hash if valid
- * @case
- * ```ts
- * // You can test it here and find more case in test/address.spec.ts
- * const result = address.fromBase58Check('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH')
- * console.log(JSON.stringify(result))
- * // => {"version":0,"hash":{"type":"Buffer","data":[117,30,118,232,25,145,150,212,84,148,28,69,209,179,163,35,241,67,59,214]}}
- * ```
  */
 function fromBase58Check(address) {
   const payload = Buffer.from(bs58check.decode(address));
@@ -63,40 +56,6 @@ function fromBase58Check(address) {
 exports.fromBase58Check = fromBase58Check;
 /**
  * decode address with bech32 specification,  return address version、address prefix and address data if valid
- * @example
- * ```ts
- * // valid case
- * fromBech32('BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4')
- * // => {version: 0, prefix: 'bc', data: <Buffer 75 1e 76 e8 19 91 96 d4 54 94 1c 45 d1 b3 a3 23 f1 43 3b d6>}
- *
- * // invalid case
- * fromBase58Check('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5')
- * // => Invalid checksum
- *
- * // invalid case
- * fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sL5k7')
- * // => Mixed-case string
- *
- * // invalid case
- * fromBase58Check('tb1pw508d6qejxtdg4y5r3zarquvzkan')
- * // => Excess padding
- *
- * // invalid case
- * fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
- * // => Excess padding
- *
- * // invalid case
- * fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
- * // => Non-zero padding
- *
- * // invalid case
- * fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3pjxtptv')
- * // => uses wrong encoding
- *
- * // invalid case
- * fromBase58Check('bc1p0xlxvlhemja6c4dqv22uapctqupfhlxm9h8z3k2e72q4k9hcz7vqh2y7hd')
- * // => uses wrong encoding
- * ```
  */
 function fromBech32(address) {
   let result;
@@ -122,13 +81,6 @@ function fromBech32(address) {
 exports.fromBech32 = fromBech32;
 /**
  * encode address hash to base58 address with version
- *
- * @example
- * ```ts
- * // valid case
- * toBase58Check('751e76e8199196d454941c45d1b3a323f1433bd6', 0)
- * // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
- * ```
  */
 function toBase58Check(hash, version) {
   (0, types_1.typeforce)(
@@ -143,13 +95,6 @@ function toBase58Check(hash, version) {
 exports.toBase58Check = toBase58Check;
 /**
  * encode address hash to bech32 address with version and prefix
- *
- * @example
- * ```ts
- * // valid case
- * toBech32('000000c4a5cad46221b2a187905e5266362b99d5e91c6ce24d165dab93e86433', 0, 'tb)
- * // => tb1qqqqqp399et2xygdj5xreqhjjvcmzhxw4aywxecjdzew6hylgvsesrxh6hy
- * ```
  */
 function toBech32(data, version, prefix) {
   const words = bech32_1.bech32.toWords(data);
@@ -161,45 +106,6 @@ function toBech32(data, version, prefix) {
 exports.toBech32 = toBech32;
 /**
  * decode address from output script with network, return address if matched
- * @example
- * ```ts
- * // valid case
- * fromOutputScript('OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG', 'bicoin)
- * // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
- *
- * // invalid case
- * fromOutputScript('031f1e68f82112b373f0fe980b3a89d212d2b5c01fb51eb25acb8b4c4b4299ce95 OP_CHECKSIG', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_TRUE 032487c2a32f7c8d57d2a93906a6457afd00697925b0e6e145d89af6d3bca33016 02308673d16987eaa010e540901cc6fe3695e758c19f46ce604e174dac315e685a OP_2 OP_CHECKMULTISIG', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_RETURN 06deadbeef03f895a2ad89fb6d696497af486cb7c644a27aa568c7a18dd06113401115185474', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_0 75', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_0 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_1 75', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_1 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
- * // => has no matching Address
- *
- * // invalid case
- * fromOutputScript('OP_1 fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f', undefined)
- * // => has no matching Address
- *
- * ```
  */
 function fromOutputScript(output, network) {
   // TODO: Network
@@ -227,24 +133,6 @@ function fromOutputScript(output, network) {
 exports.fromOutputScript = fromOutputScript;
 /**
  * encodes address to output script with network, return output script if address matched
- * @example
- * ```ts
- * // valid case
- * toOutputScript('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH', 'bicoin)
- * // => OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG
- *
- * // invalid case
- * toOutputScript('24kPZCmVgzfkpGdXExy56234MRHrsqQxNWE', undefined)
- * // => has no matching Script
- *
- * // invalid case
- * toOutputScript('BC1SW50QGDZ25J', { "bech32": "foo" })
- * // => has an invalid prefix
- *
- * // invalid case
- * toOutputScript('bc1rw5uspcuh', undefined)
- * // => has no matching Script
- * ```
  */
 function toOutputScript(address, network) {
   network = network || networks.bitcoin;

src/bufferutils.d.ts

@@ -2,7 +2,20 @@
 import * as varuint from 'varuint-bitcoin';
 export { varuint };
 export declare function readUInt64LE(buffer: Buffer, offset: number): number;
+/**
+ * Writes a 64-bit unsigned integer in little-endian format to the specified buffer at the given offset.
+ *
+ * @param buffer - The buffer to write the value to.
+ * @param value - The 64-bit unsigned integer value to write.
+ * @param offset - The offset in the buffer where the value should be written.
+ * @returns The new offset after writing the value.
+ */
 export declare function writeUInt64LE(buffer: Buffer, value: number, offset: number): number;
+/**
+ * Reverses the order of bytes in a buffer.
+ * @param buffer - The buffer to reverse.
+ * @returns A new buffer with the bytes reversed.
+ */
 export declare function reverseBuffer(buffer: Buffer): Buffer;
 export declare function cloneBuffer(buffer: Buffer): Buffer;
 /**

src/bufferutils.js

@@ -30,13 +30,26 @@ function readUInt64LE(buffer, offset) {
   return b + a;
 }
 exports.readUInt64LE = readUInt64LE;
+/**
+ * Writes a 64-bit unsigned integer in little-endian format to the specified buffer at the given offset.
+ *
+ * @param buffer - The buffer to write the value to.
+ * @param value - The 64-bit unsigned integer value to write.
+ * @param offset - The offset in the buffer where the value should be written.
+ * @returns The new offset after writing the value.
+ */
 function writeUInt64LE(buffer, value, offset) {
   verifuint(value, 0x001fffffffffffff);
   buffer.writeInt32LE(value & -1, offset);
   buffer.writeUInt32LE(Math.floor(value / 0x100000000), offset + 4);
   return offset + 8;
 }
 exports.writeUInt64LE = writeUInt64LE;
+/**
+ * Reverses the order of bytes in a buffer.
+ * @param buffer - The buffer to reverse.
+ * @returns A new buffer with the bytes reversed.
+ */
 function reverseBuffer(buffer) {
   if (buffer.length < 1) return buffer;
   let j = buffer.length - 1;

src/crypto.d.ts

@@ -10,6 +10,9 @@ type TaggedHashPrefixes = {
     [key in TaggedHashPrefix]: Buffer;
 };
 /** An object mapping tags to their tagged hash prefix of [SHA256(tag) | SHA256(tag)] */
+/**
+ * Defines the tagged hash prefixes used in the crypto module.
+ */
 export declare const TAGGED_HASH_PREFIXES: TaggedHashPrefixes;
 export declare function taggedHash(prefix: TaggedHashPrefix, data: Buffer): Buffer;
 export {};

src/crypto.js

@@ -9,6 +9,12 @@ exports.taggedHash =
   exports.sha1 =
   exports.ripemd160 =
     void 0;
+/**
+ * A module for hashing functions.
+ * include ripemd160、sha1、sha256、hash160、hash256、taggedHash
+ *
+ * @packageDocumentation
+ */
 const ripemd160_1 = require('@noble/hashes/ripemd160');
 const sha1_1 = require('@noble/hashes/sha1');
 const sha256_1 = require('@noble/hashes/sha256');
@@ -48,6 +54,9 @@ exports.TAGS = [
   '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.
+ */
 exports.TAGGED_HASH_PREFIXES = {
   'BIP0340/challenge': Buffer.from([
     123, 181, 45, 122, 159, 239, 88, 50, 62, 177, 191, 122, 64, 125, 179, 130,

src/ecc_lib.d.ts

@@ -1,3 +1,17 @@
 import { TinySecp256k1Interface } from './types';
+/**
+ * Initializes the ECC library with the provided instance.
+ * If `eccLib` is `undefined`, the library will be cleared.
+ * If `eccLib` is a new instance, it will be verified before setting it as the active library.
+ *
+ * @param eccLib The instance of the ECC library to initialize.
+ */
 export declare function initEccLib(eccLib: TinySecp256k1Interface | undefined): void;
+/**
+ * Retrieves the ECC Library instance.
+ * Throws an error if the ECC Library is not provided.
+ * You must call initEccLib() with a valid TinySecp256k1Interface instance before calling this function.
+ * @returns The ECC Library instance.
+ * @throws Error if the ECC Library is not provided.
+ */
 export declare function getEccLib(): TinySecp256k1Interface;