📄 docs: add docs fro script namespace

Author: jasonandjay

ts_src/script.ts

@@ -1,3 +1,7 @@
+/**
+ * Script tools, including decompile, compile, toASM, fromASM, toStack, isCanonicalPubKey, isCanonicalScriptSignature
+ * @packageDocumentation
+ */
 import * as bip66 from './bip66';
 import { OPS, REVERSE_OPS } from './ops';
 import { Stack } from './payments';
@@ -7,6 +11,7 @@ import * as scriptSignature from './script_signature';
 import * as types from './types';
 const { typeforce } = types;
 
+
 const OP_INT_BASE = OPS.OP_RESERVED; // OP_1 - 1
 export { OPS };
 
@@ -50,6 +55,13 @@ function singleChunkIsBuffer(buf: number | Buffer): buf is Buffer {
   return Buffer.isBuffer(buf);
 }
 
+/**
+ * Compiles an array of chunks into a Buffer.
+ * 
+ * @param chunks - The array of chunks to compile.
+ * @returns The compiled Buffer.
+ * @throws Error if the compilation fails.
+ */
 export function compile(chunks: Buffer | Stack): Buffer {
   // TODO: remove me
   if (chunksIsBuffer(chunks)) return chunks;
@@ -147,6 +159,12 @@ export function decompile(
   return chunks;
 }
 
+/**
+ * Converts the given chunks into an ASM (Assembly) string representation.
+ * If the chunks parameter is a Buffer, it will be decompiled into a Stack before conversion.
+ * @param chunks - The chunks to convert into ASM.
+ * @returns The ASM string representation of the chunks.
+ */
 export function toASM(chunks: Buffer | Array<number | Buffer>): string {
   if (chunksIsBuffer(chunks)) {
     chunks = decompile(chunks) as Stack;
@@ -167,6 +185,11 @@ export function toASM(chunks: Buffer | Array<number | Buffer>): string {
     .join(' ');
 }
 
+/**
+ * Converts an ASM string to a Buffer.
+ * @param asm The ASM string to convert.
+ * @returns The converted Buffer.
+ */
 export function fromASM(asm: string): Buffer {
   typeforce(types.String, asm);
 
@@ -182,6 +205,12 @@ export function fromASM(asm: string): Buffer {
   );
 }
 
+/**
+ * Converts the given chunks into a stack of buffers.
+ * 
+ * @param chunks - The chunks to convert.
+ * @returns The stack of buffers.
+ */
 export function toStack(chunks: Buffer | Array<number | Buffer>): Buffer[] {
   chunks = decompile(chunks) as Stack;
   typeforce(isPushOnly, chunks);

ts_src/script_number.ts

@@ -1,3 +1,13 @@
+/**
+ * Decodes a script number from a buffer.
+ * 
+ * @param buffer - The buffer containing the script number.
+ * @param maxLength - The maximum length of the script number. Defaults to 4.
+ * @param minimal - Whether the script number should be minimal. Defaults to true.
+ * @returns The decoded script number.
+ * @throws {TypeError} If the script number overflows the maximum length.
+ * @throws {Error} If the script number is not minimally encoded when minimal is true.
+ */
 export function decode(
   buffer: Buffer,
   maxLength?: number,
@@ -50,6 +60,12 @@ function scriptNumSize(i: number): number {
     : 0;
 }
 
+/**
+ * Encodes a number into a Buffer using a specific format.
+ * 
+ * @param _number - The number to encode.
+ * @returns The encoded number as a Buffer.
+ */
 export function encode(_number: number): Buffer {
   let value = Math.abs(_number);
   const size = scriptNumSize(value);

ts_src/script_signature.ts

@@ -3,6 +3,11 @@ import * as types from './types';
 const { typeforce } = types;
 
 const ZERO = Buffer.alloc(1, 0);
+/**
+ * Converts a buffer to a DER-encoded buffer.
+ * @param x - The buffer to be converted.
+ * @returns The DER-encoded buffer.
+ */
 function toDER(x: Buffer): Buffer {
   let i = 0;
   while (x[i] === 0) ++i;
@@ -12,6 +17,13 @@ function toDER(x: Buffer): Buffer {
   return x;
 }
 
+/**
+ * Converts a DER-encoded signature to a buffer.
+ * If the first byte of the input buffer is 0x00, it is skipped.
+ * The resulting buffer is 32 bytes long, filled with zeros if necessary.
+ * @param x - The DER-encoded signature.
+ * @returns The converted buffer.
+ */
 function fromDER(x: Buffer): Buffer {
   if (x[0] === 0x00) x = x.slice(1);
   const buffer = Buffer.alloc(32, 0);
@@ -26,6 +38,12 @@ interface ScriptSignature {
 }
 
 // BIP62: 1 byte hashType flag (only 0x01, 0x02, 0x03, 0x81, 0x82 and 0x83 are allowed)
+/**
+ * Decodes a buffer into a ScriptSignature object.
+ * @param buffer - The buffer to decode.
+ * @returns The decoded ScriptSignature object.
+ * @throws Error if the hashType is invalid.
+ */
 export function decode(buffer: Buffer): ScriptSignature {
   const hashType = buffer.readUInt8(buffer.length - 1);
   const hashTypeMod = hashType & ~0x80;
@@ -40,6 +58,13 @@ export function decode(buffer: Buffer): ScriptSignature {
   return { signature, hashType };
 }
 
+/**
+ * Encodes a signature and hash type into a buffer.
+ * @param signature - The signature to encode.
+ * @param hashType - The hash type to encode.
+ * @returns The encoded buffer.
+ * @throws Error if the hashType is invalid.
+ */
 export function encode(signature: Buffer, hashType: number): Buffer {
   typeforce(
     {