@opcat-labs/opcat 1.0.0 → 1.0.2

package/{lib/crypto/signature.js → cjs/crypto/signature.cjs}

@@ -1,11 +1,17 @@
 'use strict';
 
-var BN = require('./bn');
-var _ = require('../util/_');
-var $ = require('../util/preconditions');
-var JSUtil = require('../util/js');
+var BN = require('./bn.cjs');
+var _ = require('../util/_.cjs');
+var $ = require('../util/preconditions.cjs');
+var JSUtil = require('../util/js.cjs');
 
-var Signature = function Signature(r, s) {
+/**
+ * Creates a new Signature instance from BN values or an object.
+ * @constructor
+ * @param {BN|Object} r - Either a BN instance for the r value or an object containing r and s properties.
+ * @param {BN} [s] - The s value (required if r is a BN instance).
+ */
+function Signature(r, s) {
   if (!(this instanceof Signature)) {
     return new Signature(r, s);
   }
@@ -20,6 +26,16 @@ var Signature = function Signature(r, s) {
   }
 };
 
+/**
+ * Sets signature properties from an object.
+ * @param {Object} obj - Object containing signature properties
+ * @param {Buffer} [obj.r] - r value
+ * @param {Buffer} [obj.s] - s value
+ * @param {number} [obj.i] - Public key recovery parameter (0-3)
+ * @param {boolean} [obj.compressed] - Whether recovered pubkey is compressed
+ * @param {number} [obj.nhashtype] - Hash type
+ * @returns {Signature} Returns the signature instance for chaining
+ */
 Signature.prototype.set = function (obj) {
   this.r = obj.r || this.r || undefined;
   this.s = obj.s || this.s || undefined;
@@ -30,6 +46,13 @@ Signature.prototype.set = function (obj) {
   return this;
 };
 
+/**
+ * Creates a Signature instance from a compact ECDSA signature buffer.
+ * @param {Buffer} buf - The compact signature buffer (65 bytes).
+ * @returns {Signature} The parsed signature object.
+ * @throws {Error} If the input is invalid (not a Buffer, wrong length, or invalid recovery param).
+ * @static
+ */
 Signature.fromCompact = function (buf) {
   $.checkArgument(Buffer.isBuffer(buf), 'Argument is expected to be a Buffer');
 
@@ -57,6 +80,13 @@ Signature.fromCompact = function (buf) {
   return sig;
 };
 
+/**
+ * Creates a Signature instance from a DER-encoded or raw buffer.
+ * @param {Buffer} buf - The input buffer containing DER-encoded or raw signature data
+ * @param {boolean} [strict] - Whether to enforce strict DER parsing rules
+ * @returns {Signature} A new Signature instance with parsed r and s values
+ * @static
+ */
 Signature.fromDER = Signature.fromBuffer = function (buf, strict) {
   var obj = Signature.parseDER(buf, strict);
   var sig = new Signature();
@@ -68,6 +98,12 @@ Signature.fromDER = Signature.fromBuffer = function (buf, strict) {
 };
 
 // The format used in a tx
+/**
+ * Converts a transaction-format signature buffer to a Signature object.
+ * @param {Buffer} buf - The signature buffer in transaction format (DER + hash type byte)
+ * @returns {Signature} The parsed Signature object with nhashtype property set
+ * @static
+ */
 Signature.fromTxFormat = function (buf) {
   var nhashtype = buf.readUInt8(buf.length - 1);
   var derbuf = buf.slice(0, buf.length - 1);
@@ -76,13 +112,38 @@ Signature.fromTxFormat = function (buf) {
   return sig;
 };
 
+/**
+ * Creates a Signature instance from a hex-encoded string.
+ * @param {string} str - Hex-encoded signature string
+ * @returns {Signature} Signature instance parsed from DER format
+ * @static
+ */
 Signature.fromString = function (str) {
   var buf = Buffer.from(str, 'hex');
   return Signature.fromDER(buf);
 };
 
+
 /**
+ * Parses a DER formatted signature buffer into its components.
  * In order to mimic the non-strict DER encoding of OpenSSL, set strict = false.
+ * @param {Buffer} buf - The DER formatted signature buffer to parse
+ * @param {boolean} [strict=true] - Whether to perform strict length validation
+ * @returns {Object} An object containing the parsed signature components:
+ *   - header: The DER header byte (0x30)
+ *   - length: The total length of the signature components
+ *   - rheader: The R component header byte (0x02)
+ *   - rlength: The length of the R component
+ *   - rneg: Whether R is negative
+ *   - rbuf: The R component buffer
+ *   - r: The R component as a BN
+ *   - sheader: The S component header byte (0x02)
+ *   - slength: The length of the S component
+ *   - sneg: Whether S is negative
+ *   - sbuf: The S component buffer
+ *   - s: The S component as a BN
+ * @throws {Error} If the buffer is not valid DER format or length checks fail
+ * @static
  */
 Signature.parseDER = function (buf, strict) {
   $.checkArgument(Buffer.isBuffer(buf), new Error('DER formatted signature should be a buffer'));
@@ -141,6 +202,13 @@ Signature.parseDER = function (buf, strict) {
   return obj;
 };
 
+/**
+ * Converts the signature to a compact format.
+ * @param {number} [i] - The recovery ID (0, 1, 2, or 3). Defaults to the instance's `i` value.
+ * @param {boolean} [compressed] - Whether the signature is compressed. Defaults to the instance's `compressed` value.
+ * @returns {Buffer} - The compact signature as a Buffer (1 byte recovery ID + 32 bytes r + 32 bytes s).
+ * @throws {Error} - If `i` is not 0, 1, 2, or 3.
+ */
 Signature.prototype.toCompact = function (i, compressed) {
   i = typeof i === 'number' ? i : this.i;
   compressed = typeof compressed === 'boolean' ? compressed : this.compressed;
@@ -163,6 +231,12 @@ Signature.prototype.toCompact = function (i, compressed) {
   return Buffer.concat([b1, b2, b3]);
 };
 
+/**
+ * Converts the signature to DER format.
+ * Handles negative values by prepending a zero byte if necessary.
+ * 
+ * @returns {Buffer} The DER-encoded signature.
+ */
 Signature.prototype.toBuffer = Signature.prototype.toDER = function () {
   var rnbuf = this.r.toBuffer();
   var snbuf = this.s.toBuffer();
@@ -189,6 +263,10 @@ Signature.prototype.toBuffer = Signature.prototype.toDER = function () {
   return der;
 };
 
+/**
+ * Converts the signature to a hexadecimal string representation.
+ * @returns {string} The DER-encoded signature in hexadecimal format.
+ */
 Signature.prototype.toString = function () {
   var buf = this.toDER();
   return buf.toString('hex');
@@ -205,6 +283,10 @@ Signature.prototype.toString = function () {
  * in which case a single 0 byte is necessary and even required).
  *
  * See https://bitcointalk.org/index.php?topic=8392.msg127623#msg127623
+ * 
+ * @param {Buffer} buf - The buffer containing the signature to verify
+ * @returns {boolean} True if the signature is valid DER-encoded, false otherwise
+ * @static
  */
 Signature.isTxDER = function (buf) {
   if (buf.length < 9) {
@@ -272,10 +354,12 @@ Signature.isTxDER = function (buf) {
   return true;
 };
 
+
 /**
- * Compares to bitcoind's IsLowDERSignature
+ * Checks if the signature's S value is within the valid range (low-S).
  * See also ECDSA signature algorithm which enforces this.
  * See also BIP 62, "low S values in signatures"
+ * @returns {boolean} True if S is between 1 and the upper bound (0x7F...A0), false otherwise.
  */
 Signature.prototype.hasLowS = function () {
   if (
@@ -287,9 +371,13 @@ Signature.prototype.hasLowS = function () {
   return true;
 };
 
+
 /**
- * @returns true if the nhashtype is exactly equal to one of the standard options or combinations thereof.
- * Translated from bitcoind's IsDefinedHashtypeSignature
+ * Checks if the signature has a defined hashtype.
+ * - Validates that nhashtype is a natural number
+ * - Accepts with or without Signature.SIGHASH_ANYONECANPAY by ignoring the bit
+ * - Verifies the hashtype is between SIGHASH_ALL and SIGHASH_SINGLE
+ * @returns {boolean} True if the hashtype is valid, false otherwise
  */
 Signature.prototype.hasDefinedHashtype = function () {
   if (!JSUtil.isNaturalNumber(this.nhashtype)) {
@@ -303,6 +391,11 @@ Signature.prototype.hasDefinedHashtype = function () {
   return true;
 };
 
+/**
+ * Converts the signature to transaction format by concatenating the DER-encoded signature
+ * with the hash type byte.
+ * @returns {Buffer} The signature in transaction format (DER + hash type byte).
+ */
 Signature.prototype.toTxFormat = function () {
   var derbuf = this.toDER();
   var buf = Buffer.alloc(1);
@@ -310,16 +403,73 @@ Signature.prototype.toTxFormat = function () {
   return Buffer.concat([derbuf, buf]);
 };
 
+/**
+ * Signature hash type for signing all inputs/outputs (default).
+ * @constant {number}
+ * @default 0x01
+ */
 Signature.SIGHASH_ALL = 0x01;
+/**
+ * Flag indicating that no outputs are signed (only inputs are signed).
+ * Used in signature hashing to specify which parts of the transaction are included in the hash.
+ * @constant {number}
+ * @default 0x02
+ */
 Signature.SIGHASH_NONE = 0x02;
+/**
+ * Signature hash type for single input signing (0x03).
+ * @constant {number}
+ * @default 0x03
+ */
 Signature.SIGHASH_SINGLE = 0x03;
+/**
+ * Bit flag indicating that only the current input is signed (others can be modified).
+ * Used in Bitcoin signature hashing (SIGHASH type).
+ * @constant {number}
+ * @default 0x80
+ */
 Signature.SIGHASH_ANYONECANPAY = 0x80;
 
+/**
+ * Signature hash type for signing all inputs/outputs (default).
+ * @constant {number}
+ * @default 0x01
+ */
 Signature.ALL = Signature.SIGHASH_ALL
+/**
+ * Flag indicating that no outputs are signed (only inputs are signed).
+ * Used in signature hashing to specify which parts of the transaction are included in the hash.
+ * @constant {number}
+ * @default 0x02
+ */
 Signature.NONE = Signature.SIGHASH_NONE
+/**
+ * Signature hash type for single input signing (0x03).
+ * @constant {number}
+ * @default 0x03
+ */
 Signature.SINGLE = Signature.SIGHASH_SINGLE
+/**
+ * Bitwise flag combination for signature hash types: 
+ * SIGHASH_ALL (default) with ANYONECANPAY modifier.
+ * Allows anyone to add inputs to the transaction.
+ * @constant {number}
+ * @default 0x81
+ */
 Signature.ANYONECANPAY_ALL = Signature.SIGHASH_ALL | Signature.SIGHASH_ANYONECANPAY
+/**
+ * Bitwise flag combination for a signature that allows anyone to pay (no output locking)
+ * and doesn't commit to any outputs (SIGHASH_NONE).
+ * @constant {number}
+ * @default 0x82
+ */
 Signature.ANYONECANPAY_NONE = Signature.SIGHASH_NONE | Signature.SIGHASH_ANYONECANPAY
+/**
+ * Bitwise flag combination for signature allowing anyone to pay (SIGHASH_ANYONECANPAY) 
+ * with single output mode (SIGHASH_SINGLE).
+ * @constant {number}
+ * @default 0x83
+ */
 Signature.ANYONECANPAY_SINGLE = Signature.SIGHASH_SINGLE | Signature.SIGHASH_ANYONECANPAY
 
 module.exports = Signature;

package/{lib/encoding/base58.js → cjs/encoding/base58.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var _ = require('../util/_');
+var _ = require('../util/_.cjs');
 var bs58 = require('bs58');
 
 /**
@@ -18,7 +18,7 @@ var ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'.spli
  *
  * @param {object} obj Can be a string or buffer.
  */
-var Base58 = function Base58(obj) {
+function Base58(obj) {
   if (!(this instanceof Base58)) {
     return new Base58(obj);
   }
@@ -31,6 +31,12 @@ var Base58 = function Base58(obj) {
   }
 };
 
+/**
+ * Checks if all characters in the input are valid Base58 characters.
+ * @param {string|Buffer} chars - The input characters to validate (can be a string or Buffer).
+ * @returns {boolean} True if all characters are valid Base58, false otherwise.
+ * @static
+ */
 Base58.validCharacters = function validCharacters(chars) {
   if (Buffer.isBuffer(chars)) {
     chars = chars.toString();
@@ -42,6 +48,12 @@ Base58.validCharacters = function validCharacters(chars) {
   );
 };
 
+/**
+ * Sets the buffer property from the given object.
+ * @param {Object} obj - The object containing the buffer to set.
+ * @param {Buffer} [obj.buf] - The buffer to assign. If not provided, retains current buffer or sets to undefined.
+ * @returns {Base58} Returns the instance for chaining.
+ */
 Base58.prototype.set = function (obj) {
   this.buf = obj.buf || this.buf || undefined;
   return this;
@@ -52,6 +64,8 @@ Base58.prototype.set = function (obj) {
  *
  * @param {Buffer} buf Any buffer to be encoded.
  * @returns {string} A Base 58 encoded string.
+ * @throws {Error} If the input is not a buffer.
+ * @static
  */
 Base58.encode = function (buf) {
   if (!Buffer.isBuffer(buf)) {
@@ -65,6 +79,8 @@ Base58.encode = function (buf) {
  *
  * @param {string} str A Base 58 encoded string.
  * @returns {Buffer} The decoded buffer.
+ * @throws {Error} If the input is not a string.
+ * @static
  */
 Base58.decode = function (str) {
   if (typeof str !== 'string') {
@@ -73,37 +89,77 @@ Base58.decode = function (str) {
   return Buffer.from(bs58.decode(str));
 };
 
+/**
+ * Sets the internal buffer to the provided buffer and returns the instance for chaining.
+ * @param {Buffer} buf - The buffer to set as the internal buffer.
+ * @returns {Base58} The instance for method chaining.
+ */
 Base58.prototype.fromBuffer = function (buf) {
   this.buf = buf;
   return this;
 };
 
+/**
+ * Creates a Base58 encoded string from a buffer.
+ * @param {Buffer} buf - The input buffer to encode.
+ * @returns {Base58} A new Base58 instance containing the encoded string.
+ * @static
+ */
 Base58.fromBuffer = function (buf) {
   return new Base58().fromBuffer(buf);
 };
 
+/**
+ * Converts a hex string to Base58 encoded string.
+ * @param {string} hex - The hex string to convert.
+ * @returns {string} The Base58 encoded string.
+ * @static
+ */
 Base58.fromHex = function (hex) {
   return Base58.fromBuffer(Buffer.from(hex, 'hex'));
 };
 
+/**
+ * Converts a Base58 encoded string to a buffer and stores it in the instance.
+ * @param {string} str - The Base58 encoded string to decode.
+ * @returns {Base58} The current instance for chaining.
+ */
 Base58.prototype.fromString = function (str) {
   var buf = Base58.decode(str);
   this.buf = buf;
   return this;
 };
 
+/**
+ * Creates a Base58 instance from a string input.
+ * @param {string} str - The string to convert to Base58.
+ * @returns {Base58} A new Base58 instance containing the encoded string.
+ * @static
+ */
 Base58.fromString = function (str) {
   return new Base58().fromString(str);
 };
 
+/**
+ * Returns the internal buffer containing the Base58 encoded data.
+ * @returns {Buffer} The raw buffer representation of the Base58 data.
+ */
 Base58.prototype.toBuffer = function () {
   return this.buf;
 };
 
+/**
+ * Converts the Base58 encoded data to a hexadecimal string.
+ * @returns {string} Hexadecimal representation of the Base58 data.
+ */
 Base58.prototype.toHex = function () {
   return this.toBuffer().toString('hex');
 };
 
+/**
+ * Converts the Base58 instance to its string representation.
+ * @returns {string} The Base58 encoded string.
+ */
 Base58.prototype.toString = function () {
   return Base58.encode(this.buf);
 };

package/cjs/encoding/base58check.cjs

@@ -0,0 +1,192 @@
+'use strict';
+
+var _ = require('../util/_.cjs');
+var Base58 = require('./base58.cjs');
+var Hash = require('../crypto/hash.cjs');
+
+/**
+ * A Base58check object can encode/decodd Base 58, which is used primarily for
+ * string-formatted Bitcoin addresses and private keys. This is the same as
+ * Base58, except that it includes a checksum to prevent accidental mistypings.
+ * @constructor
+ * @param {Buffer|string} obj Can be a string or buffer.
+ */
+function Base58Check(obj) {
+  if (!(this instanceof Base58Check)) {
+    return new Base58Check(obj);
+  }
+  if (Buffer.isBuffer(obj)) {
+    var buf = obj;
+    this.fromBuffer(buf);
+  } else if (typeof obj === 'string') {
+    var str = obj;
+    this.fromString(str);
+  }
+};
+
+/**
+ * Sets the buffer property from the given object.
+ * @param {Object} obj - The object containing the buffer to set.
+ * @returns {Base58Check} Returns the instance for chaining.
+ */
+Base58Check.prototype.set = function (obj) {
+  this.buf = obj.buf || this.buf || undefined;
+  return this;
+};
+
+/**
+ * Validates the checksum of Base58Check encoded data.
+ * @param {Buffer|string} data - The data to validate, either as a Buffer or Base58 encoded string.
+ * @param {Buffer|string} [checksum] - Optional checksum to validate against, either as a Buffer or Base58 encoded string.
+ * If not provided, the last 4 bytes of the data will be used as checksum.
+ * @returns {boolean} True if the computed checksum matches the provided/embedded checksum.
+ * @static
+ */
+Base58Check.validChecksum = function validChecksum(data, checksum) {
+  if (_.isString(data)) {
+    data = Buffer.from(Base58.decode(data));
+  }
+  if (_.isString(checksum)) {
+    checksum = Buffer.from(Base58.decode(checksum));
+  }
+  if (!checksum) {
+    checksum = data.slice(-4);
+    data = data.slice(0, -4);
+  }
+  return Base58Check.checksum(data).toString('hex') === checksum.toString('hex');
+};
+
+/**
+ * Decodes a Base58Check encoded string and verifies its checksum.
+ * @param {string} s - The Base58Check encoded string to decode.
+ * @returns {Buffer} The decoded data (excluding checksum).
+ * @throws {Error} If input is not a string, too short, or checksum mismatch.
+ * @static
+ */
+Base58Check.decode = function (s) {
+  if (typeof s !== 'string') {
+    throw new Error('Input must be a string');
+  }
+
+  var buf = Buffer.from(Base58.decode(s));
+
+  if (buf.length < 4) {
+    throw new Error('Input string too short');
+  }
+
+  var data = buf.slice(0, -4);
+  var csum = buf.slice(-4);
+
+  var hash = Hash.sha256sha256(data);
+  var hash4 = hash.slice(0, 4);
+
+  if (csum.toString('hex') !== hash4.toString('hex')) {
+    throw new Error('Checksum mismatch');
+  }
+
+  return data;
+};
+
+/**
+ * Calculates the checksum for a given buffer using double SHA-256 hash.
+ * The checksum is the first 4 bytes of the double-hashed result.
+ * @param {Buffer} buffer - The input buffer to calculate checksum for
+ * @returns {Buffer} The 4-byte checksum
+ * @static
+ */
+Base58Check.checksum = function (buffer) {
+  return Hash.sha256sha256(buffer).slice(0, 4);
+};
+
+/**
+ * Encodes a buffer into Base58Check format.
+ * @param {Buffer} buf - The input buffer to encode
+ * @returns {string} The Base58Check encoded string
+ * @throws {Error} If input is not a Buffer
+ * @static
+ */
+Base58Check.encode = function (buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new Error('Input must be a buffer');
+  }
+  var checkedBuf = Buffer.alloc(buf.length + 4);
+  var hash = Base58Check.checksum(buf);
+  buf.copy(checkedBuf);
+  hash.copy(checkedBuf, buf.length);
+  return Base58.encode(checkedBuf);
+};
+
+/**
+ * Sets the internal buffer to the provided Buffer object.
+ * @param {Buffer} buf - The buffer to set as the internal state.
+ * @returns {Base58Check} Returns the instance for chaining.
+ */
+Base58Check.prototype.fromBuffer = function (buf) {
+  this.buf = buf;
+  return this;
+};
+
+/**
+ * Creates a Base58Check encoded string from a buffer.
+ * @param {Buffer} buf - The input buffer to encode.
+ * @returns {Base58Check} A new Base58Check instance containing the encoded data.
+ */
+Base58Check.fromBuffer = function (buf) {
+  return new Base58Check().fromBuffer(buf);
+};
+
+/**
+ * Converts a hex string to a Base58Check encoded string.
+ * @param {string} hex - The hex string to convert.
+ * @returns {string} The Base58Check encoded string.
+ */
+Base58Check.fromHex = function (hex) {
+  return Base58Check.fromBuffer(Buffer.from(hex, 'hex'));
+};
+
+/**
+ * Converts a Base58Check encoded string to a buffer and stores it in the instance.
+ * @param {string} str - The Base58Check encoded string to decode.
+ * @returns {Base58Check} Returns the instance for chaining.
+ */
+Base58Check.prototype.fromString = function (str) {
+  var buf = Base58Check.decode(str);
+  this.buf = buf;
+  return this;
+};
+
+/**
+ * Converts a Base58Check-encoded string into a Base58 object.
+ * @param {string} str - The Base58Check-encoded string to decode.
+ * @returns {Base58} A new Base58 instance containing the decoded data.
+ */
+Base58Check.fromString = function (str) {
+  var buf = Base58Check.decode(str);
+  return new Base58(buf);
+};
+
+/**
+ * Returns the internal buffer containing the Base58Check encoded data.
+ * @returns {Buffer} The raw buffer representation of the Base58Check data.
+ */
+Base58Check.prototype.toBuffer = function () {
+  return this.buf;
+};
+
+/**
+ * Converts the Base58Check encoded data to a hexadecimal string.
+ * @returns {string} Hexadecimal representation of the data.
+ */
+Base58Check.prototype.toHex = function () {
+  return this.toBuffer().toString('hex');
+};
+
+/**
+ * Converts the Base58Check instance to its string representation.
+ * @returns {string} The Base58Check encoded string.
+ */
+Base58Check.prototype.toString = function () {
+  return Base58Check.encode(this.buf);
+};
+
+module.exports = Base58Check;