📄 docs: add docs for payments module

Author: jasonandjay

ts_src/payments/bip341.ts

@@ -34,6 +34,13 @@ const isHashBranch = (ht: HashTree): ht is HashBranch =>
  */
 export type HashTree = HashLeaf | HashBranch;
 
+/**
+ * Calculates the root hash from a given control block and leaf hash.
+ * @param controlBlock - The control block buffer.
+ * @param leafHash - The leaf hash buffer.
+ * @returns The root hash buffer.
+ * @throws {TypeError} If the control block length is less than 33.
+ */
 export function rootHashFromPath(
   controlBlock: Buffer,
   leafHash: Buffer,

ts_src/payments/embed.ts

@@ -15,6 +15,13 @@ function stacksEqual(a: Buffer[], b: Buffer[]): boolean {
 }
 
 // output: OP_RETURN ...
+/**
+ * Embeds data in a Bitcoin payment.
+ * @param a - The payment object.
+ * @param opts - Optional payment options.
+ * @returns The modified payment object.
+ * @throws {TypeError} If there is not enough data or if the output is invalid.
+ */
 export function p2data(a: Payment, opts?: PaymentOpts): Payment {
   if (!a.data && !a.output) throw new TypeError('Not enough data');
   opts = Object.assign({ validate: true }, opts || {});

ts_src/payments/index.ts

@@ -1,3 +1,10 @@
+/**
+ * Represents a payment object, which is used to create a payment.
+ * 
+ * Supports P2PKH、P2SH、P2WPKH、P2WSH、P2TR and so on
+ *
+ * @packageDocumentation
+ */
 import { Network } from '../networks';
 import { Taptree } from '../types';
 import { p2data as embed } from './embed';

ts_src/payments/p2ms.ts

@@ -17,6 +17,13 @@ function stacksEqual(a: Buffer[], b: Buffer[]): boolean {
 
 // input: OP_0 [signatures ...]
 // output: m [pubKeys ...] n OP_CHECKMULTISIG
+/**
+ * Represents a function that creates a Pay-to-Multisig (P2MS) payment object.
+ * @param a - The payment object.
+ * @param opts - Optional payment options.
+ * @returns The created payment object.
+ * @throws {TypeError} If the provided data is not valid.
+ */
 export function p2ms(a: Payment, opts?: PaymentOpts): Payment {
   if (
     !a.input &&

ts_src/payments/p2pk.ts

@@ -7,6 +7,14 @@ const OPS = bscript.OPS;
 
 // input: {signature}
 // output: {pubKey} OP_CHECKSIG
+/**
+ * Creates a pay-to-public-key (P2PK) payment object.
+ * 
+ * @param a - The payment object containing the necessary data.
+ * @param opts - Optional payment options.
+ * @returns The P2PK payment object.
+ * @throws {TypeError} If the required data is not provided or if the data is invalid.
+ */
 export function p2pk(a: Payment, opts?: PaymentOpts): Payment {
   if (!a.input && !a.output && !a.pubkey && !a.input && !a.signature)
     throw new TypeError('Not enough data');

ts_src/payments/p2pkh.ts

@@ -9,6 +9,14 @@ const OPS = bscript.OPS;
 
 // input: {signature} {pubkey}
 // output: OP_DUP OP_HASH160 {hash160(pubkey)} OP_EQUALVERIFY OP_CHECKSIG
+/**
+ * Creates a Pay-to-Public-Key-Hash (P2PKH) payment object.
+ *
+ * @param a - The payment object containing the necessary data.
+ * @param opts - Optional payment options.
+ * @returns The P2PKH payment object.
+ * @throws {TypeError} If the required data is not provided or if the data is invalid.
+ */
 export function p2pkh(a: Payment, opts?: PaymentOpts): Payment {
   if (!a.address && !a.hash && !a.output && !a.pubkey && !a.input)
     throw new TypeError('Not enough data');

ts_src/payments/p2sh.ts

@@ -24,6 +24,14 @@ function stacksEqual(a: Buffer[], b: Buffer[]): boolean {
 // input: [redeemScriptSig ...] {redeemScript}
 // witness: <?>
 // output: OP_HASH160 {hash160(redeemScript)} OP_EQUAL
+/**
+ * Creates a Pay-to-Script-Hash (P2SH) payment object.
+ *
+ * @param a - The payment object containing the necessary data.
+ * @param opts - Optional payment options.
+ * @returns The P2SH payment object.
+ * @throws {TypeError} If the required data is not provided or if the data is invalid.
+ */
 export function p2sh(a: Payment, opts?: PaymentOpts): Payment {
   if (!a.address && !a.hash && !a.output && !a.redeem && !a.input)
     throw new TypeError('Not enough data');

ts_src/payments/p2tr.ts

@@ -19,6 +19,14 @@ const OPS = bscript.OPS;
 const TAPROOT_WITNESS_VERSION = 0x01;
 const ANNEX_PREFIX = 0x50;
 
+/**
+ * Creates a Pay-to-Taproot (P2TR) payment object.
+ *
+ * @param a - The payment object containing the necessary data for P2TR.
+ * @param opts - Optional payment options.
+ * @returns The P2TR payment object.
+ * @throws {TypeError} If the provided data is invalid or insufficient.
+ */
 export function p2tr(a: Payment, opts?: PaymentOpts): Payment {
   if (
     !a.address &&

ts_src/payments/p2wpkh.ts

@@ -12,6 +12,14 @@ const EMPTY_BUFFER = Buffer.alloc(0);
 // witness: {signature} {pubKey}
 // input: <>
 // output: OP_0 {pubKeyHash}
+/**
+ * Creates a pay-to-witness-public-key-hash (p2wpkh) payment object.
+ *
+ * @param a - The payment object containing the necessary data.
+ * @param opts - Optional payment options.
+ * @returns The p2wpkh payment object.
+ * @throws {TypeError} If the required data is missing or invalid.
+ */
 export function p2wpkh(a: Payment, opts?: PaymentOpts): Payment {
   if (!a.address && !a.hash && !a.output && !a.pubkey && !a.witness)
     throw new TypeError('Not enough data');

ts_src/payments/p2wsh.ts

@@ -33,6 +33,14 @@ function chunkHasUncompressedPubkey(chunk: StackElement): boolean {
 // input: <>
 // witness: [redeemScriptSig ...] {redeemScript}
 // output: OP_0 {sha256(redeemScript)}
+/**
+ * Creates a Pay-to-Witness-Script-Hash (P2WSH) payment object.
+ * 
+ * @param a - The payment object containing the necessary data.
+ * @param opts - Optional payment options.
+ * @returns The P2WSH payment object.
+ * @throws {TypeError} If the required data is missing or invalid.
+ */
 export function p2wsh(a: Payment, opts?: PaymentOpts): Payment {
   if (!a.address && !a.hash && !a.output && !a.redeem && !a.witness)
     throw new TypeError('Not enough data');