📄 docs: comment address namespace

Author: jasonandjay

ts_src/address.ts

@@ -1,18 +1,35 @@
+/**
+ * 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
+ *
+ * addresses support P2PKH、P2SH、P2WPKH、P2WSH、P2TR and so on
+ *
+ * @packageDocumentation
+ */
 import { Network } from './networks';
 import * as networks from './networks';
 import * as payments from './payments';
 import * as bscript from './script';
 import { typeforce, tuple, Hash160bit, UInt8 } from './types';
 import { bech32, bech32m } from 'bech32';
 import * as bs58check from 'bs58check';
+
+/** base58check decode result */
 export interface Base58CheckResult {
+  /** address hash */
   hash: Buffer;
+  /** address version: 0x00 for P2PKH, 0x05 for P2SH */
   version: number;
 }
 
+/** bech32 decode result */
 export interface Bech32Result {
+  /** address version: 0x00 for P2WPKH、P2WSH, 0x01 for P2TR*/
   version: number;
+  /** address prefix: bc for P2WPKH、P2WSH、P2TR */
   prefix: string;
+  /** address data：20 bytes for P2WPKH, 32 bytes for P2WSH、P2TR */
   data: Buffer;
 }
 
@@ -52,6 +69,23 @@ function _toFutureSegwitAddress(output: Buffer, network: Network): string {
   return toBech32(data, version, network.bech32);
 }
 
+/**
+ * decode address with base58 specification,  return address version and address hash if valid
+ * @example
+ * ```ts
+ * // valid case
+ * fromBase58Check('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH')
+ * // => {version: 0, hash: <Buffer 75 1e 76 e8 19 91 96 d4 54 94 1c 45 d1 b3 a3 23 f1 43 3b d6>}
+ *
+ * // invalid case: address is too short
+ * fromBase58Check('7SeEnXWPaCCALbVrTnszCVGfRU8cGfx')
+ * // => throw new TypeError('7SeEnXWPaCCALbVrTnszCVGfRU8cGfx is too short')
+ *
+ * // invalid case: address is too long
+ * fromBase58Check('j9ywUkWg2fTQrouxxh5rSZhRvrjMkEUfuiKe')
+ * // => throw new TypeError('j9ywUkWg2fTQrouxxh5rSZhRvrjMkEUfuiKe is too long')
+ * ```
+ */
 export function fromBase58Check(address: string): Base58CheckResult {
   const payload = Buffer.from(bs58check.decode(address));
 
@@ -65,6 +99,43 @@ export function fromBase58Check(address: string): Base58CheckResult {
   return { version, hash };
 }
 
+/**
+ * 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 function fromBech32(address: string): Bech32Result {
   let result;
   let version;
@@ -90,6 +161,16 @@ export function fromBech32(address: string): Bech32Result {
   };
 }
 
+/**
+ * encode address hash to base58 address with version
+ *
+ * @example
+ * ```ts
+ * // valid case
+ * toBase58Check('751e76e8199196d454941c45d1b3a323f1433bd6', 0)
+ * // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
+ * ```
+ */
 export function toBase58Check(hash: Buffer, version: number): string {
   typeforce(tuple(Hash160bit, UInt8), arguments);
 
@@ -100,6 +181,16 @@ export function toBase58Check(hash: Buffer, version: number): string {
   return bs58check.encode(payload);
 }
 
+/**
+ * encode address hash to bech32 address with version and prefix
+ *
+ * @example
+ * ```ts
+ * // valid case
+ * toBech32('000000c4a5cad46221b2a187905e5266362b99d5e91c6ce24d165dab93e86433', 0, 'tb)
+ * // => tb1qqqqqp399et2xygdj5xreqhjjvcmzhxw4aywxecjdzew6hylgvsesrxh6hy
+ * ```
+ */
 export function toBech32(
   data: Buffer,
   version: number,
@@ -113,6 +204,48 @@ export function toBech32(
     : bech32m.encode(prefix, words);
 }
 
+/**
+ * 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 function fromOutputScript(output: Buffer, network?: Network): string {
   // TODO: Network
   network = network || networks.bitcoin;
@@ -139,6 +272,27 @@ export function fromOutputScript(output: Buffer, network?: Network): string {
   throw new Error(bscript.toASM(output) + ' has no matching Address');
 }
 
+/**
+ * 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 function toOutputScript(address: string, network?: Network): Buffer {
   network = network || networks.bitcoin;
 

ts_src/index.ts

@@ -7,6 +7,7 @@ import * as script from './script';
 export { address, crypto, networks, payments, script };
 
 export { Block } from './block';
+/** @hidden */
 export { TaggedHashPrefix } from './crypto';
 export {
   Psbt,
@@ -17,10 +18,12 @@ export {
   HDSigner,
   HDSignerAsync,
 } from './psbt';
+/** @hidden */
 export { OPS as opcodes } from './ops';
 export { Transaction } from './transaction';
-
+/** @hidden */
 export { Network } from './networks';
+/** @hidden */
 export {
   Payment,
   PaymentCreator,

ts_src/psbt.ts

@@ -92,6 +92,7 @@ const DEFAULT_OPTS: PsbtOpts = {
  * There are 6 roles that this class fulfills. (Explained in BIP174)
  *
  * Creator: This can be done with `new Psbt()`
+ *
  * Updater: This can be done with `psbt.addInput(input)`, `psbt.addInputs(inputs)`,
  *   `psbt.addOutput(output)`, `psbt.addOutputs(outputs)` when you are looking to
  *   add new inputs and outputs to the PSBT, and `psbt.updateGlobal(itemObject)`,
@@ -102,20 +103,24 @@ const DEFAULT_OPTS: PsbtOpts = {
  *   data for updateOutput.
  *   For a list of what attributes should be what types. Check the bip174 library.
  *   Also, check the integration tests for some examples of usage.
+ *
  * Signer: There are a few methods. signAllInputs and signAllInputsAsync, which will search all input
  *   information for your pubkey or pubkeyhash, and only sign inputs where it finds
  *   your info. Or you can explicitly sign a specific input with signInput and
  *   signInputAsync. For the async methods you can create a SignerAsync object
  *   and use something like a hardware wallet to sign with. (You must implement this)
+ *
  * Combiner: psbts can be combined easily with `psbt.combine(psbt2, psbt3, psbt4 ...)`
  *   the psbt calling combine will always have precedence when a conflict occurs.
  *   Combine checks if the internal bitcoin transaction is the same, so be sure that
  *   all sequences, version, locktime, etc. are the same before combining.
+ *
  * Input Finalizer: This role is fairly important. Not only does it need to construct
  *   the input scriptSigs and witnesses, but it SHOULD verify the signatures etc.
  *   Before running `psbt.finalizeAllInputs()` please run `psbt.validateSignaturesOfAllInputs()`
  *   Running any finalize method will delete any data in the input(s) that are no longer
  *   needed due to the finalized scripts containing the information.
+ *
  * Transaction Extractor: This role will perform some checks before returning a
  *   Transaction object. Such as fee rate not being larger than maximumFeeRate etc.
  */