@opcat-labs/opcat 1.0.1 → 1.0.3

package/{lib/script/script.js → cjs/script/script.cjs}

@@ -1,19 +1,19 @@
 'use strict';
 
-var Address = require('../address');
-var BufferWriter = require('../encoding/bufferwriter');
-var Hash = require('../crypto/hash');
-var Opcode = require('../opcode');
-var PublicKey = require('../publickey');
-var Signature = require('../crypto/signature');
-var Networks = require('../networks');
-var $ = require('../util/preconditions');
-var _ = require('../util/_');
-var errors = require('../errors');
-var JSUtil = require('../util/js');
-const decodeScriptChunks = require('../encoding/decode-script-chunks');
-const decodeASM = require('../encoding/decode-asm');
-const encodeHex = require('../encoding/encode-hex');
+var Address = require('../address.cjs');
+var BufferWriter = require('../encoding/bufferwriter.cjs');
+var Hash = require('../crypto/hash.cjs');
+var Opcode = require('../opcode.cjs');
+var PublicKey = require('../publickey.cjs');
+var Signature = require('../crypto/signature.cjs');
+var Networks = require('../networks.cjs');
+var $ = require('../util/preconditions.cjs');
+var _ = require('../util/_.cjs');
+var errors = require('../errors/index.cjs');
+var JSUtil = require('../util/js.cjs');
+const decodeScriptChunks = require('../encoding/decode-script-chunks.cjs');
+const decodeASM = require('../encoding/decode-asm.cjs');
+const encodeHex = require('../encoding/encode-hex.cjs');
 
 // These WeakMap caches allow the objects themselves to maintain their immutability
 const SCRIPT_TO_CHUNKS_CACHE = new WeakMap();
@@ -25,9 +25,9 @@ const SCRIPT_TO_CHUNKS_CACHE = new WeakMap();
  * See https://en.bitcoin.it/wiki/Script
  *
  * @constructor
- * @param {Object|string|Buffer=} from optional data to populate script
+ * @param {Object|string|Buffer} [from] optional data to populate script
  */
-var Script = function Script(from) {
+function Script(from) {
   if (!(this instanceof Script)) {
     return new Script(from);
   }
@@ -48,6 +48,14 @@ var Script = function Script(from) {
   }
 };
 
+/**
+ * Sets the script content from an object.
+ * @param {Object} obj - The source object containing either chunks array or buffer.
+ * @param {Array} [obj.chunks] - Optional array of chunks to create script from.
+ * @param {Buffer} [obj.buffer] - Optional buffer containing script data.
+ * @returns {Script} Returns the script instance for chaining.
+ * @throws Will throw if argument is invalid (not object or missing required buffer).
+ */
 Script.prototype.set = function (obj) {
   $.checkArgument(_.isObject(obj));
   if (obj.chunks && _.isArray(obj.chunks)) {
@@ -61,6 +69,12 @@ Script.prototype.set = function (obj) {
   return this;
 };
 
+/**
+ * Creates a Script instance from a Buffer.
+ * @param {Buffer} buffer - The buffer containing the script data.
+ * @returns {Script} A new Script instance with the provided buffer.
+ * @throws {Error} Throws if the input is not a Buffer.
+ */
 Script.fromBuffer = function (buffer) {
   $.checkArgument(Buffer.isBuffer(buffer));
   var script = new Script();
@@ -68,6 +82,13 @@ Script.fromBuffer = function (buffer) {
   return script;
 };
 
+/**
+ * Creates a Script instance from an array of opcode chunks.
+ * Handles different pushdata opcodes (OP_PUSHDATA1, OP_PUSHDATA2, OP_PUSHDATA4)
+ * by writing appropriate length prefixes before the buffer data.
+ * @param {Array} chunks - Array of opcode chunks containing opcodenum and optional buf/len
+ * @returns {Script} A new Script instance with compiled buffer
+ */
 Script.fromChunks = function (chunks) {
   var script = new Script();
 
@@ -96,18 +117,41 @@ Script.fromChunks = function (chunks) {
   return script;
 };
 
+/**
+ * Returns the underlying buffer of the script.
+ * @returns {Buffer} The script's buffer data.
+ */
 Script.prototype.toBuffer = function () {
   return this.buffer;
 };
 
+/**
+ * Creates a Script instance from ASM (Assembly) formatted string.
+ * @param {string} str - ASM formatted string to decode
+ * @returns {Script} Script instance created from decoded ASM
+ */
 Script.fromASM = function (str) {
   return Script.fromBuffer(decodeASM(str));
 };
 
+/**
+ * Creates a Script instance from a hex string.
+ * @param {string} str - Hex string to convert to Script.
+ * @returns {Script} New Script instance created from the hex string.
+ */
 Script.fromHex = function (str) {
   return new Script(Buffer.from(str, 'hex'));
 };
 
+/**
+ * Converts a string representation of a script into a Script object.
+ * Handles hex strings, empty strings, and space-separated opcode tokens.
+ * For pushdata operations (OP_PUSHDATA1/2/4), validates format and length.
+ * Throws errors for invalid script formats or data lengths.
+ * @param {string} str - The script string to parse (hex or opcode tokens)
+ * @returns {Script} The constructed Script object
+ * @throws {Error} When script format is invalid or data lengths don't match
+ */
 Script.fromString = function (str) {
   if (JSUtil.isHexa(str) || str.length === 0) {
     return new Script(Buffer.from(str, 'hex'));
@@ -162,10 +206,22 @@ Script.fromString = function (str) {
   return Script.fromChunks(chunks);
 };
 
+/**
+ * Gets a portion of the script's buffer as a new buffer.
+ * @param {number} [start] - The beginning index of the specified portion of the buffer.
+ * @param {number} [end] - The end index of the specified portion of the buffer.
+ * @returns {Buffer} A new Buffer that contains the specified portion of the original buffer.
+ */
 Script.prototype.slice = function (start, end) {
   return this.buffer.slice(start, end);
 };
 
+/**
+ * Gets the chunks associated with the Script instance.
+ * @memberof Script.prototype
+ * @name chunks
+ * @type {Array}
+ */
 Object.defineProperty(Script.prototype, 'chunks', {
   get() {
     if (SCRIPT_TO_CHUNKS_CACHE.has(this)) return SCRIPT_TO_CHUNKS_CACHE.get(this);
@@ -175,12 +231,27 @@ Object.defineProperty(Script.prototype, 'chunks', {
   },
 });
 
+/**
+ * Gets the length of the script in bytes.
+ * @memberof Script.prototype
+ * @name length
+ * @type {number}
+ */
 Object.defineProperty(Script.prototype, 'length', {
   get() {
     return this.buffer.length;
   },
 });
 
+/**
+ * Converts a script chunk to a string representation based on the given type.
+ * Handles both data chunks and opcode chunks, with special formatting for ASM output.
+ * 
+ * @param {Object} chunk - The script chunk to convert, containing opcodenum and optional buf/len
+ * @param {string} type - The output type ('asm' or other)
+ * @returns {string} The formatted string representation of the chunk
+ * @private
+ */
 Script.prototype._chunkToString = function (chunk, type) {
   var opcodenum = chunk.opcodenum;
   var asm = type === 'asm';
@@ -235,6 +306,11 @@ Script.prototype._chunkToString = function (chunk, type) {
   return str;
 };
 
+/**
+ * Converts the script chunks to ASM (Assembly) format string representation.
+ * Iterates through each chunk and appends its ASM string representation.
+ * @returns {string} The ASM formatted string (excluding the first character).
+ */
 Script.prototype.toASM = function () {
   var str = '';
   var chunks = this.chunks;
@@ -246,6 +322,12 @@ Script.prototype.toASM = function () {
   return str.substr(1);
 };
 
+/**
+ * Converts the script's chunks to a string representation.
+ * Iterates through each chunk and appends its string representation,
+ * then removes the leading character from the result.
+ * @returns {string} The concatenated string of all chunks.
+ */
 Script.prototype.toString = function () {
   var str = '';
   for (var i = 0; i < this.chunks.length; i++) {
@@ -256,18 +338,33 @@ Script.prototype.toString = function () {
   return str.substr(1);
 };
 
+/**
+ * Converts the script's buffer to a hexadecimal string.
+ * @returns {string} Hex-encoded representation of the script buffer.
+ */
 Script.prototype.toHex = function () {
   return encodeHex(this.buffer);
 };
 
+/**
+ * Custom inspect method for Script instances.
+ * @returns {string} String representation of the Script object in format '<Script: [content]>'.
+ */
 Script.prototype.inspect = function () {
   return '<Script: ' + this.toString() + '>';
 };
 
 // script classification methods
 
+
 /**
- * @returns {boolean} if this is a pay to pubkey hash output script
+ * Checks if the script is a standard public key hash output script (P2PKH).
+ * @returns {boolean} True if the script matches the P2PKH pattern:
+ * - OP_DUP
+ * - OP_HASH160
+ * - 20-byte hash
+ * - OP_EQUALVERIFY
+ * - OP_CHECKSIG
  */
 Script.prototype.isPublicKeyHashOut = function () {
   return !!(
@@ -281,8 +378,12 @@ Script.prototype.isPublicKeyHashOut = function () {
   );
 };
 
+
 /**
- * @returns {boolean} if this is a pay to public key hash input script
+ * Checks if the script contains a valid public key hash.
+ * @returns {boolean} True if the script has exactly 2 chunks (signature and public key),
+ *                   the signature starts with 0x30, and the public key has a valid version
+ *                   and length (65 bytes for versions 0x04/0x06/0x07, 33 bytes for 0x02/0x03).
  */
 Script.prototype.isPublicKeyHashIn = function () {
   if (this.chunks.length === 2) {
@@ -306,18 +407,33 @@ Script.prototype.isPublicKeyHashIn = function () {
   return false;
 };
 
+/**
+ * Gets the public key from a script output.
+ * @returns {Buffer} The public key buffer.
+ * @throws {Error} If the script is not a public key output.
+ */
 Script.prototype.getPublicKey = function () {
   $.checkState(this.isPublicKeyOut(), "Can't retrieve PublicKey from a non-PK output");
   return this.chunks[0].buf;
 };
 
+/**
+ * Retrieves the PublicKeyHash from a script output.
+ * @returns {Buffer} The PublicKeyHash buffer.
+ * @throws {Error} If the script output is not a PublicKeyHash output.
+ */
 Script.prototype.getPublicKeyHash = function () {
   $.checkState(this.isPublicKeyHashOut(), "Can't retrieve PublicKeyHash from a non-PKH output");
   return this.chunks[2].buf;
 };
 
+
 /**
- * @returns {boolean} if this is a public key output script
+ * Checks if the script is a standard public key output script.
+ * @returns {boolean} True if the script matches the standard public key output format:
+ *                    - Contains exactly 2 chunks
+ *                    - First chunk is a valid public key buffer (65 bytes for uncompressed, 33 bytes for compressed)
+ *                    - Second chunk is OP_CHECKSIG opcode
  */
 Script.prototype.isPublicKeyOut = function () {
   if (
@@ -341,8 +457,10 @@ Script.prototype.isPublicKeyOut = function () {
   return false;
 };
 
+
 /**
- * @returns {boolean} if this is a pay to public key input script
+ * Checks if the script contains a valid public key signature.
+ * @returns {boolean} True if the script has exactly one chunk that starts with 0x30 (DER signature marker), false otherwise.
  */
 Script.prototype.isPublicKeyIn = function () {
   if (this.chunks.length === 1) {
@@ -354,8 +472,15 @@ Script.prototype.isPublicKeyIn = function () {
   return false;
 };
 
+
 /**
- * @returns {boolean} if this is a mutlsig output script
+ * Checks if the script is a multisig output script.
+ * @returns {boolean} True if the script matches the multisig output pattern:
+ * - Has more than 3 chunks
+ * - First chunk is a small integer opcode
+ * - Middle chunks are all buffers
+ * - Second-to-last chunk is a small integer opcode
+ * - Last chunk is OP_CHECKMULTISIG
  */
 Script.prototype.isMultisigOut = function () {
   return (
@@ -391,8 +516,10 @@ Script.prototype.decodeMultisigOut = function () {
   };
 };
 
+
 /**
- * @returns {boolean} if this is a multisig input script
+ * Checks if the script is a multisig input script.
+ * @returns {boolean} True if the script is a valid multisig input (starts with OP_0 and has valid DER signatures).
  */
 Script.prototype.isMultisigIn = function () {
   return (
@@ -404,8 +531,10 @@ Script.prototype.isMultisigIn = function () {
   );
 };
 
+
 /**
- * @returns {boolean} true if this is a valid standard OP_RETURN output
+ * Checks if the script is a data-only output script (OP_RETURN followed by push-only data).
+ * @returns {boolean} True if the script is a valid data-only output, false otherwise.
  */
 Script.prototype.isDataOut = function () {
   var step1 = this.buffer.length >= 1 && this.buffer[0] === Opcode.OP_RETURN;
@@ -415,6 +544,11 @@ Script.prototype.isDataOut = function () {
   return script2.isPushOnly();
 };
 
+/**
+ * Checks if the script is a safe data output script.
+ * A safe data output script must start with OP_FALSE followed by a valid data output script.
+ * @returns {boolean} True if the script is a safe data output, false otherwise.
+ */
 Script.prototype.isSafeDataOut = function () {
   if (this.buffer.length < 2) {
     return false;
@@ -453,9 +587,10 @@ Script.prototype.getData = function () {
   throw new Error('Unrecognized script type to get data from');
 };
 
+
 /**
- * @returns {boolean} if the script is only composed of data pushing
- * opcodes or small int opcodes (OP_0, OP_1, ..., OP_16)
+ * Checks if the script consists only of push operations (OP_0 to OP_16) or data push operations (OP_PUSHDATA1/2/4).
+ * @returns {boolean} True if all chunks are push operations, false otherwise.
  */
 Script.prototype.isPushOnly = function () {
   return _.every(this.chunks, function (chunk) {
@@ -468,20 +603,66 @@ Script.prototype.isPushOnly = function () {
   });
 };
 
+/**
+ * Registry for script types. 
+ * @namespace
+ */
 Script.types = {};
+/**
+ * Represents the 'Unknown' type constant for script types.
+ * @type {string}
+ */
 Script.types.UNKNOWN = 'Unknown';
+/**
+ * Defines the display text for the public key output script type.
+ * @type {string}
+ */
 Script.types.PUBKEY_OUT = 'Pay to public key';
+/**
+ * Script type constant for spending from a public key input.
+ * @type {string}
+ */
 Script.types.PUBKEY_IN = 'Spend from public key';
+/**
+ * Script type constant for Pay to Public Key Hash (P2PKH) output.
+ * @type {string}
+ */
 Script.types.PUBKEYHASH_OUT = 'Pay to public key hash';
+/**
+ * Constant defining the display string for public key hash input script type.
+ * @type {string}
+ */
 Script.types.PUBKEYHASH_IN = 'Spend from public key hash';
+/**
+ * Script type constant for Pay to Script Hash (P2SH) output.
+ * @type {string}
+ */
 Script.types.SCRIPTHASH_OUT = 'Pay to script hash';
+/**
+ * Constant defining the string representation for spending from a script hash input type.
+ * @type {string}
+ */
 Script.types.SCRIPTHASH_IN = 'Spend from script hash';
+/**
+ * Multisig output script type identifier.
+ * @type {string}
+ */
 Script.types.MULTISIG_OUT = 'Pay to multisig';
+/**
+ * Multisig input script type - represents spending from a multisig address.
+ */
 Script.types.MULTISIG_IN = 'Spend from multisig';
+/**
+ * Constant defining the type string for data output operations.
+ * @type {string}
+ */
 Script.types.DATA_OUT = 'Data push';
+/**
+ * Constant defining the type string for safe data output operations.
+ * @type {string}
+ */
 Script.types.SAFE_DATA_OUT = 'Safe data push';
 
-Script.OP_RETURN_STANDARD_SIZE = 220;
 
 /**
  * @returns {object} The Script type if it is a known form,
@@ -556,8 +737,12 @@ Script.prototype.prepend = function (obj) {
   return this;
 };
 
+
 /**
- * Compares a script with another script
+ * Compares this script with another script for equality.
+ * @param {Script} script - The script to compare with.
+ * @returns {boolean} True if the scripts have identical buffer contents, false otherwise.
+ * @throws {Error} If the provided argument is not a Script instance.
  */
 Script.prototype.equals = function (script) {
   $.checkState(script instanceof Script, 'Must provide another script');
@@ -573,18 +758,25 @@ Script.prototype.equals = function (script) {
   return true;
 };
 
+
 /**
  * Adds a script element to the end of the script.
- *
- * @param {*} obj a string, number, Opcode, Buffer, or object to add
- * @returns {Script} this script instance
- *
+ * @param {Object} obj - The object to add.
+ * @returns {Script} Returns the script instance for chaining.
  */
 Script.prototype.add = function (obj) {
   this._addByType(obj, false);
   return this;
 };
 
+/**
+ * Adds a script element to the script by type.
+ * Handles strings, numbers, Opcode instances, Buffers, Script instances, or objects.
+ * @param {string|number|Opcode|Buffer|Script|Object} obj - The element to add
+ * @param {boolean} [prepend=false] - Whether to prepend (true) or append (false)
+ * @throws {Error} If the input is an invalid script chunk
+ * @private
+ */
 Script.prototype._addByType = function (obj, prepend) {
   if (typeof obj === 'string') {
     this._addOpcode(obj, prepend);
@@ -604,6 +796,12 @@ Script.prototype._addByType = function (obj, prepend) {
   }
 };
 
+/**
+ * Inserts a buffer at the specified position in the script's buffer.
+ * @param {Buffer} buf - The buffer to insert.
+ * @param {boolean} prepend - If true, inserts before the existing buffer; otherwise appends after.
+ * @private
+ */
 Script.prototype._insertAtPosition = function (buf, prepend) {
   var bw = new BufferWriter();
 
@@ -617,6 +815,13 @@ Script.prototype._insertAtPosition = function (buf, prepend) {
   this.buffer = bw.toBuffer();
 };
 
+/**
+ * Adds an opcode to the script.
+ * @param {number|Opcode|string} opcode - The opcode to add (can be a number, Opcode instance, or string).
+ * @param {boolean} [prepend=false] - Whether to prepend the opcode (true) or append it (false).
+ * @returns {Script} Returns the script instance for chaining.
+ * @throws {errors.Script.InvalidOpcode} Throws if the opcode value exceeds 255.
+ */
 Script.prototype._addOpcode = function (opcode, prepend) {
   var op;
   if (typeof opcode === 'number') {
@@ -642,6 +847,14 @@ Script.prototype._addOpcode = function (opcode, prepend) {
   return this;
 };
 
+/**
+ * Adds a buffer to the script with appropriate opcode based on buffer length.
+ * Handles different buffer sizes by using corresponding pushdata opcodes.
+ * @param {Buffer} buf - The buffer to add to the script
+ * @param {boolean} [prepend] - Whether to prepend the buffer (default: append)
+ * @returns {Script} Returns the script instance for chaining
+ * @throws {Error} If buffer length exceeds maximum allowed size (2^32)
+ */
 Script.prototype._addBuffer = function (buf, prepend) {
   var bw = new BufferWriter();
   var opcodenum;
@@ -676,10 +889,19 @@ Script.prototype._addBuffer = function (buf, prepend) {
   return this;
 };
 
+/**
+ * Creates a shallow copy of the Script instance.
+ * @returns {Script} A new Script instance with the same buffer content.
+ */
 Script.prototype.clone = function () {
   return Script.fromBuffer(this.buffer.slice());
 };
 
+/**
+ * Removes all OP_CODESEPARATOR opcodes from the script chunks.
+ * Updates the script buffer with the filtered chunks and clears the cache.
+ * @returns {Script} The modified script instance for chaining.
+ */
 Script.prototype.removeCodeseparators = function () {
   var chunks = [];
   for (var i = 0; i < this.chunks.length; i++) {
@@ -716,16 +938,14 @@ Script.prototype.subScript = function (n) {
   return this;
 };
 
-// high level script builder methods
-
+            
 /**
- * @returns {Script} a new Multisig output script for given public keys,
- * requiring m of those public keys to spend
- * @param {PublicKey[]} publicKeys - list of all public keys controlling the output
- * @param {number} threshold - amount of required signatures to spend the output
- * @param {Object=} opts - Several options:
- *        - noSorting: defaults to false, if true, don't sort the given
- *                      public keys before creating the script
+ * Builds a multisig output script from given public keys and threshold.
+ * @param {Array} publicKeys - Array of public keys to include in the multisig
+ * @param {number} threshold - Minimum number of signatures required
+ * @param {Object} [opts] - Optional parameters
+ * @param {boolean} [opts.noSorting] - If true, skips sorting of public keys
+ * @returns {Script} The constructed multisig script
  */
 Script.buildMultisigOut = function (publicKeys, threshold, opts) {
   $.checkArgument(
@@ -779,10 +999,12 @@ Script.buildMultisigIn = function (pubkeys, threshold, signatures, opts) {
   return s;
 };
 
+
 /**
- * @returns {Script} a new pay to public key hash output for the given
- * address or public key
- * @param {(Address|PublicKey)} to - destination address or public key
+ * Builds a standard P2PKH (Pay-to-Public-Key-Hash) script for a given recipient.
+ * @param {PublicKey|Address|string} to - Recipient's public key, address, or address string
+ * @returns {Script} A P2PKH script with the format: `OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG`
+ * @throws {Error} If 'to' argument is undefined or invalid type
  */
 Script.buildPublicKeyHashOut = function (to) {
   $.checkArgument(!_.isUndefined(to));
@@ -802,9 +1024,11 @@ Script.buildPublicKeyHashOut = function (to) {
   return s;
 };
 
+
 /**
- * @returns {Script} a new pay to public key output for the given
- *  public key
+ * Builds a standard P2PK (Pay-to-Public-Key) script output.
+ * @param {PublicKey} pubkey - The public key to create the script for
+ * @returns {Script} A new script containing the public key and OP_CHECKSIG opcode
  */
 Script.buildPublicKeyOut = function (pubkey) {
   $.checkArgument(pubkey instanceof PublicKey);
@@ -815,8 +1039,8 @@ Script.buildPublicKeyOut = function (pubkey) {
 
 /**
  * @returns {Script} a new OP_RETURN script with data
- * @param {(string|Buffer|Array)} data - the data to embed in the output - it is a string, buffer, or array of strings or buffers
- * @param {(string)} encoding - the type of encoding of the string(s)
+ * @param {string|Buffer|Array} data - the data to embed in the output - it is a string, buffer, or array of strings or buffers
+ * @param {string} encoding - the type of encoding of the string(s)
  */
 Script.buildDataOut = function (data, encoding) {
   $.checkArgument(
@@ -842,8 +1066,8 @@ Script.buildDataOut = function (data, encoding) {
 
 /**
  * @returns {Script} a new OP_RETURN script with data
- * @param {(string|Buffer|Array)} data - the data to embed in the output - it is a string, buffer, or array of strings or buffers
- * @param {(string)} encoding - the type of encoding of the string(s)
+ * @param {string|Buffer|Array} data - the data to embed in the output - it is a string, buffer, or array of strings or buffers
+ * @param {string} encoding - the type of encoding of the string(s)
  */
 Script.buildSafeDataOut = function (data, encoding) {
   var s2 = Script.buildDataOut(data, encoding);
@@ -858,7 +1082,7 @@ Script.buildSafeDataOut = function (data, encoding) {
  * Builds a scriptSig (a script for an input) that signs a public key output script.
  *
  * @param {Signature|Buffer} signature - a Signature object, or the signature in DER canonical encoding
- * @param {number=} sigtype - the type of the signature (defaults to SIGHASH_ALL)
+ * @param {number} [sigtype] - the type of the signature (defaults to SIGHASH_ALL)
  */
 Script.buildPublicKeyIn = function (signature, sigtype) {
   $.checkArgument(signature instanceof Signature || Buffer.isBuffer(signature));
@@ -877,7 +1101,7 @@ Script.buildPublicKeyIn = function (signature, sigtype) {
  *
  * @param {Buffer|string|PublicKey} publicKey
  * @param {Signature|Buffer} signature - a Signature object, or the signature in DER canonical encoding
- * @param {number=} sigtype - the type of the signature (defaults to SIGHASH_ALL)
+ * @param {number} [sigtype] - the type of the signature (defaults to SIGHASH_ALL)
  */
 Script.buildPublicKeyHashIn = function (publicKey, signature, sigtype) {
   $.checkArgument(signature instanceof Signature || Buffer.isBuffer(signature));
@@ -891,15 +1115,21 @@ Script.buildPublicKeyHashIn = function (publicKey, signature, sigtype) {
   return script;
 };
 
+
 /**
- * @returns {Script} an empty script
+ * Creates and returns an empty Script instance.
+ * @returns {Script} A new empty Script object.
  */
 Script.empty = function () {
   return new Script();
 };
 
+
 /**
- * @return {Script} an output script built from the address
+ * Creates a Script from an address.
+ * @param {Address|string} address - The address to convert to a script.
+ * @returns {Script} A Pay-to-PublicKeyHash (P2PKH) script for the given address.
+ * @throws {errors.Script.UnrecognizedAddress} If the address type is not supported.
  */
 Script.fromAddress = function (address) {
   address = Address(address);
@@ -909,11 +1139,15 @@ Script.fromAddress = function (address) {
   throw new errors.Script.UnrecognizedAddress(address);
 };
 
+
 /**
- * Will return the associated address information object
- * @return {Address|boolean}
+ * Gets address information for the script.
+ * For input scripts, returns input address info.
+ * For output scripts, returns output address info.
+ * For general scripts, tries output address info first, falls back to input if not available.
+ * @returns {Object} Address information object
  */
-Script.prototype.getAddressInfo = function (opts) {
+Script.prototype.getAddressInfo = function () {
   if (this._isInput) {
     return this._getInputAddressInfo();
   } else if (this._isOutput) {
@@ -927,10 +1161,12 @@ Script.prototype.getAddressInfo = function (opts) {
   }
 };
 
+
 /**
- * Will return the associated output scriptPubKey address information object
- * @return {Address|boolean}
- * @private
+ * Gets the output address information from the script.
+ * @returns {Object|boolean} An object containing the hash buffer and address type if the script is a public key hash output, otherwise false.
+ * @property {Buffer} info.hashBuffer - The hash buffer of the address.
+ * @property {number} info.type - The type of the address (Address.PayToPublicKeyHash).
  */
 Script.prototype._getOutputAddressInfo = function () {
   var info = {};
@@ -960,26 +1196,32 @@ Script.prototype._getInputAddressInfo = function () {
   return info;
 };
 
+
 /**
- * @param {Network=} network
- * @return {Address|boolean} the associated address for this script if possible, or false
+ * Converts the script to an Address object for the specified network.
+ * @param {string|Network} [network] - optianal, the network name or identifier.
+ * @returns {Address} The derived Address object.
+ * @throws {errors.Script.CantDeriveAddress} If address information cannot be derived from the script.
  */
 Script.prototype.toAddress = function (network) {
   var info = this.getAddressInfo();
   if (!info) {
-    return false;
+    throw new errors.Script.CantDeriveAddress(this);
   }
   info.network = Networks.get(network) || this._network || Networks.defaultNetwork;
   return new Address(info);
 };
 
 /**
+ * Finds and deletes a matching script chunk from the current script.
  * Analogous to bitcoind's FindAndDelete. Find and delete equivalent chunks,
  * typically used with push data chunks.  Note that this will find and delete
  * not just the same data, but the same data with the same push data op as
  * produced by default. i.e., if a pushdata in a tx does not use the minimal
  * pushdata op, then when you try to remove the data it is pushing, it will not
  * be removed, because they do not use the same pushdata op.
+ * @param {Script} script - The script chunk to find and delete.
+ * @returns {Script} The modified script instance after deletion.
  */
 Script.prototype.findAndDelete = function (script) {
   var buf = script.toBuffer();
@@ -997,9 +1239,20 @@ Script.prototype.findAndDelete = function (script) {
   return this;
 };
 
+
 /**
- * Comes from bitcoind's script interpreter CheckMinimalPush function
- * @returns {boolean} if the chunk {i} is the smallest way to push that particular data.
+ * Checks if a script chunk uses the minimal push operation possible.
+ * 
+ * @param {number} i - Index of the chunk to check
+ * @returns {boolean} True if the chunk uses minimal push operation, false otherwise
+ * 
+ * The function verifies if the chunk could have been represented with:
+ * - OP_0 for empty buffer
+ * - OP_1 to OP_16 for single-byte values 1-16
+ * - OP_1NEGATE for 0x81
+ * - Direct push for buffers ≤75 bytes
+ * - OP_PUSHDATA1 for buffers ≤255 bytes
+ * - OP_PUSHDATA2 for buffers ≤65535 bytes
  */
 Script.prototype.checkMinimalPush = function (i) {
   var chunk = this.chunks[i];
@@ -1034,6 +1287,7 @@ Script.prototype.checkMinimalPush = function (i) {
  * Comes from bitcoind's script DecodeOP_N function
  * @param {number} opcode
  * @returns {number} numeric value in range of 0 to 16
+ * @private
  */
 Script.prototype._decodeOP_N = function (opcode) {
   if (opcode === Opcode.OP_0) {
@@ -1045,10 +1299,11 @@ Script.prototype._decodeOP_N = function (opcode) {
   }
 };
 
+
 /**
- * Comes from bitcoind's script GetSigOpCount(boolean) function
- * @param {boolean} use current (true) or pre-version-0.6 (false) logic
- * @returns {number} number of signature operations required by this script
+ * Counts the number of signature operations in the script.
+ * @param {boolean} [accurate=true] - Whether to count accurately for OP_CHECKMULTISIG(VERIFY).
+ * @returns {number} The total count of signature operations.
  */
 Script.prototype.getSignatureOperationsCount = function (accurate) {
   accurate = _.isUndefined(accurate) ? true : accurate;