quantumcoin 6.14.5 → 7.0.2

package/src/utils/address.js

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview Address utilities (QuantumCoin 32-byte address format).
+ *
+ * QuantumCoin addresses are 32 bytes (66 hex characters including 0x).
+ * Most helpers here are thin wrappers around `quantum-coin-js-sdk`.
+ */
+
+const qcsdk = require("quantum-coin-js-sdk");
+const { assertArgument, makeError } = require("../errors");
+const { arrayify, bytesToHex, hexToBytes, isHexString, normalizeHex } = require("../internal/hex");
+const { sha256 } = require("./hashing");
+
+function _requireInitialized() {
+  // The spec requires Initialize() to be called before using the SDK.
+  // config.js tracks initialization state for this package.
+  // eslint-disable-next-line global-require
+  const { isInitialized } = require("../../config");
+  if (!isInitialized()) {
+    throw makeError("QuantumCoin SDK not initialized. Call Initialize() first.", "UNKNOWN_ERROR", {
+      operation: "address-utils",
+    });
+  }
+}
+
+/**
+ * Checks if string is a valid address (32 bytes, 66 hex characters).
+ * @param {string} address
+ * @returns {boolean}
+ */
+function isAddress(address) {
+  if (typeof address !== "string") return false;
+  _requireInitialized();
+  const result = qcsdk.isAddressValid(address);
+  return result === true;
+}
+
+/**
+ * Returns normalized address.
+ * Note: QuantumCoin checksumming uses QuantumCoin conventions; currently this normalizes to lowercase.
+ * @param {string} address
+ * @returns {string}
+ */
+function getAddress(address) {
+  assertArgument(typeof address === "string", "address must be a string", "address", address);
+  _requireInitialized();
+  const norm = normalizeHex(address);
+  assertArgument(qcsdk.isAddressValid(norm) === true, "invalid address", "address", address);
+  return norm;
+}
+
+/**
+ * Returns true if value is an object implementing Addressable (has getAddress()).
+ * @param {any} value
+ * @returns {boolean}
+ */
+function isAddressable(value) {
+  return Boolean(value && typeof value === "object" && typeof value.getAddress === "function");
+}
+
+/**
+ * Resolve an AddressLike into a string address.
+ * For QuantumCoin, ENS is not supported.
+ * @param {any} target
+ * @returns {string|Promise<string>}
+ */
+function resolveAddress(target) {
+  if (typeof target === "string") return getAddress(target);
+  if (isAddressable(target)) return target.getAddress();
+  if (target && typeof target.then === "function") {
+    return Promise.resolve(target).then((v) => resolveAddress(v));
+  }
+  throw makeError("unsupported AddressLike", "INVALID_ARGUMENT", { target });
+}
+
+/**
+ * Calculates contract address from deployer and nonce.
+ * @param {{ from: string, nonce: number }} tx
+ * @returns {string}
+ */
+function getContractAddress(tx) {
+  _requireInitialized();
+  assertArgument(tx && typeof tx === "object", "invalid tx", "tx", tx);
+  const from = getAddress(tx.from);
+  assertArgument(Number.isInteger(tx.nonce) && tx.nonce >= 0, "invalid nonce", "nonce", tx.nonce);
+  const out = qcsdk.createAddress(from, tx.nonce);
+  if (typeof out !== "string") throw makeError("createAddress failed", "UNKNOWN_ERROR", { from, nonce: tx.nonce });
+  return normalizeHex(out);
+}
+
+/**
+ * Alias for getContractAddress.
+ * @param {{ from: string, nonce: number }} tx
+ * @returns {string}
+ */
+function getCreateAddress(tx) {
+  return getContractAddress(tx);
+}
+
+/**
+ * Calculates CREATE2 contract address.
+ * @param {string} from
+ * @param {string} salt
+ * @param {string} initCodeHash
+ * @returns {string}
+ */
+function getCreate2Address(from, salt, initCodeHash) {
+  _requireInitialized();
+  const f = getAddress(from);
+  assertArgument(isHexString(salt), "invalid salt", "salt", salt);
+  assertArgument(isHexString(initCodeHash), "invalid initCodeHash", "initCodeHash", initCodeHash);
+  const out = qcsdk.createAddress2(f, normalizeHex(salt), normalizeHex(initCodeHash));
+  if (typeof out !== "string") throw makeError("createAddress2 failed", "UNKNOWN_ERROR", { from: f });
+  return normalizeHex(out);
+}
+
+/**
+ * Computes address from a public key.
+ * @param {string|Uint8Array} key
+ * @returns {string}
+ */
+function computeAddress(key) {
+  _requireInitialized();
+  const bytes = typeof key === "string" ? hexToBytes(key) : arrayify(key);
+  const pubArr = Array.from(bytes);
+  const out = qcsdk.addressFromPublicKey(pubArr);
+  if (typeof out !== "string") throw makeError("addressFromPublicKey failed", "UNKNOWN_ERROR", {});
+  return normalizeHex(out);
+}
+
+function _digestMessage(message) {
+  const bytes = typeof message === "string" ? new TextEncoder().encode(message) : arrayify(message);
+  const digestHex = sha256(bytes);
+  const digest = Array.from(hexToBytes(digestHex));
+  assertArgument(digest.length === 32, "invalid digest length", "digest", digest.length);
+  return digest;
+}
+
+function _signatureToBytes(signature) {
+  assertArgument(typeof signature === "string", "signature must be a hex string", "signature", signature);
+  assertArgument(isHexString(signature), "invalid signature hex", "signature", signature);
+  return Array.from(hexToBytes(signature));
+}
+
+/**
+ * Verifies a message signature and recovers the address.
+ * @param {string|Uint8Array} message
+ * @param {string} signature Hex string signature
+ * @returns {string}
+ */
+function verifyMessage(message, signature) {
+  return recoverAddress(message, signature);
+}
+
+/**
+ * Recovers the address from a message signature.
+ * @param {string|Uint8Array} message
+ * @param {string} signature Hex string signature
+ * @returns {string}
+ */
+function recoverAddress(message, signature) {
+  _requireInitialized();
+  const digest = _digestMessage(message);
+  const sigBytes = _signatureToBytes(signature);
+  const pubHex = qcsdk.publicKeyFromSignature(digest, sigBytes);
+  if (typeof pubHex !== "string") throw makeError("publicKeyFromSignature failed", "UNKNOWN_ERROR", {});
+  const addr = computeAddress(pubHex);
+  return addr;
+}
+
+module.exports = {
+  isAddress,
+  getAddress,
+  isAddressable,
+  resolveAddress,
+  getContractAddress,
+  getCreateAddress,
+  getCreate2Address,
+  computeAddress,
+  verifyMessage,
+  recoverAddress,
+};
+

package/src/utils/encoding.d.ts

@@ -0,0 +1,120 @@
+export type BytesLike = string | Uint8Array;
+/**
+ * @typedef {string | Uint8Array} BytesLike
+ */
+/**
+ * Converts bytes to UTF-8 string.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+export function toUtf8String(data: BytesLike): string;
+/**
+ * Converts string to UTF-8 bytes.
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+export function toUtf8Bytes(str: string): Uint8Array;
+/**
+ * Converts data to hex string.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+export function toHex(data: BytesLike): string;
+/**
+ * Alias for toHex.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+export function hexlify(data: BytesLike): string;
+/**
+ * Converts data to byte array.
+ * @param {BytesLike} data
+ * @returns {Uint8Array}
+ */
+export function arrayify(data: BytesLike): Uint8Array;
+/**
+ * Concatenates byte arrays and returns a hex string.
+ * @param {BytesLike[]} items
+ * @returns {string}
+ */
+export function concat(items: BytesLike[]): string;
+/**
+ * Strips leading zeros from a hex string.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+export function stripZerosLeft(data: BytesLike): string;
+/**
+ * Encodes a short UTF-8 string into a bytes32 hex string.
+ * @param {string} text
+ * @returns {string}
+ */
+export function encodeBytes32String(text: string): string;
+/**
+ * Decodes a bytes32 hex string into a UTF-8 string (trailing zeros stripped).
+ * @param {BytesLike} bytes
+ * @returns {string}
+ */
+export function decodeBytes32String(bytes: BytesLike): string;
+/**
+ * Decode Base58 string to bytes.
+ * @param {string} data
+ * @returns {Uint8Array}
+ */
+export function decodeBase58(data: string): Uint8Array;
+/**
+ * Base64 decode to bytes.
+ * @param {string} data
+ * @returns {Uint8Array}
+ */
+export function decodeBase64(data: string): Uint8Array;
+/**
+ * Encode BytesLike as Base58.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+export function encodeBase58(data: BytesLike): string;
+/**
+ * Base64 encode BytesLike.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+export function encodeBase64(data: BytesLike): string;
+/**
+ * Returns UTF-8 code points for a string.
+ * @param {string} str
+ * @returns {number[]}
+ */
+export function toUtf8CodePoints(str: string): number[];
+import { isHexString } from "../internal/hex";
+/**
+ * Returns true if value is BytesLike.
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isBytesLike(value: any): boolean;
+/**
+ * Pads a BytesLike value to the left with zeros (byte length).
+ * @param {BytesLike} value
+ * @param {number} length
+ * @returns {string}
+ */
+export function zeroPad(value: BytesLike, length: number): string;
+/**
+ * Pads a hex value (interpreted as bytes) to the left with zeros (byte length).
+ * @param {BytesLike} value
+ * @param {number} length
+ * @returns {string}
+ */
+export function zeroPadValue(value: BytesLike, length: number): string;
+/**
+ * Solidity packed encoding.
+ * This is a complex helper in ethers.js; in QuantumCoin.js it is currently not implemented.
+ * @throws
+ */
+export function solidityPacked(): void;
+export function solidityPackedKeccak256(): void;
+export function solidityPackedSha256(): void;
+import { bytesToHex } from "../internal/hex";
+import { hexToBytes } from "../internal/hex";
+export { isHexString, bytesToHex, hexToBytes };

package/src/utils/encoding.js

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview Encoding/decoding helpers (ethers.js v6 compatible names).
+ *
+ * Notes:
+ * - QuantumCoin addresses are 32 bytes (not 20).
+ * - This module intentionally uses only built-in Node.js APIs.
+ */
+
+const {
+  isUint8Array,
+  normalizeHex,
+  isHexString,
+  strip0x,
+  add0x,
+  hexToBytes,
+  bytesToHex,
+  utf8ToBytes,
+  bytesToUtf8,
+  arrayify: _arrayify,
+} = require("../internal/hex");
+
+/**
+ * @typedef {string | Uint8Array} BytesLike
+ */
+
+/**
+ * Converts bytes to UTF-8 string.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+function toUtf8String(data) {
+  return bytesToUtf8(arrayify(data));
+}
+
+/**
+ * Converts string to UTF-8 bytes.
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+function toUtf8Bytes(str) {
+  return utf8ToBytes(str);
+}
+
+/**
+ * Converts data to hex string.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+function toHex(data) {
+  if (typeof data === "string") return normalizeHex(data);
+  return bytesToHex(arrayify(data));
+}
+
+/**
+ * Alias for toHex.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+function hexlify(data) {
+  return toHex(data);
+}
+
+/**
+ * Converts data to byte array.
+ * @param {BytesLike} data
+ * @returns {Uint8Array}
+ */
+function arrayify(data) {
+  return _arrayify(data);
+}
+
+/**
+ * Returns true if value is BytesLike.
+ * @param {any} value
+ * @returns {boolean}
+ */
+function isBytesLike(value) {
+  return (typeof value === "string" && isHexString(value)) || isUint8Array(value);
+}
+
+/**
+ * Concatenates byte arrays and returns a hex string.
+ * @param {BytesLike[]} items
+ * @returns {string}
+ */
+function concat(items) {
+  if (!Array.isArray(items)) throw new TypeError("items must be an array");
+  const parts = items.map((i) => arrayify(i));
+  const len = parts.reduce((a, b) => a + b.length, 0);
+  const out = new Uint8Array(len);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return bytesToHex(out);
+}
+
+/**
+ * Strips leading zeros from a hex string.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+function stripZerosLeft(data) {
+  const hex = toHex(data);
+  let h = strip0x(hex);
+  h = h.replace(/^0+/, "");
+  if (h.length === 0) return "0x";
+  if (h.length % 2 !== 0) h = "0" + h;
+  return add0x(h);
+}
+
+/**
+ * Pads a BytesLike value to the left with zeros (byte length).
+ * @param {BytesLike} value
+ * @param {number} length
+ * @returns {string}
+ */
+function zeroPad(value, length) {
+  const bytes = arrayify(value);
+  if (bytes.length > length) throw new RangeError("value exceeds length");
+  const out = new Uint8Array(length);
+  out.set(bytes, length - bytes.length);
+  return bytesToHex(out);
+}
+
+/**
+ * Pads a hex value (interpreted as bytes) to the left with zeros (byte length).
+ * @param {BytesLike} value
+ * @param {number} length
+ * @returns {string}
+ */
+function zeroPadValue(value, length) {
+  return zeroPad(value, length);
+}
+
+/**
+ * Encodes a short UTF-8 string into a bytes32 hex string.
+ * @param {string} text
+ * @returns {string}
+ */
+function encodeBytes32String(text) {
+  const bytes = toUtf8Bytes(text);
+  if (bytes.length > 32) throw new RangeError("string too long (max 32 bytes)");
+  const out = new Uint8Array(32);
+  out.set(bytes, 0);
+  return bytesToHex(out);
+}
+
+/**
+ * Decodes a bytes32 hex string into a UTF-8 string (trailing zeros stripped).
+ * @param {BytesLike} bytes
+ * @returns {string}
+ */
+function decodeBytes32String(bytes) {
+  const b = arrayify(bytes);
+  if (b.length !== 32) throw new RangeError("invalid bytes32 length");
+  let end = b.length;
+  while (end > 0 && b[end - 1] === 0) end--;
+  return bytesToUtf8(b.slice(0, end));
+}
+
+/**
+ * Base64 decode to bytes.
+ * @param {string} data
+ * @returns {Uint8Array}
+ */
+function decodeBase64(data) {
+  const buf = Buffer.from(data, "base64");
+  return new Uint8Array(buf);
+}
+
+/**
+ * Base64 encode BytesLike.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+function encodeBase64(data) {
+  return Buffer.from(arrayify(data)).toString("base64");
+}
+
+// Minimal base58 implementation (Bitcoin alphabet) for compatibility with ethers helpers.
+const _B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const _B58_INDEX = new Map(_B58_ALPHABET.split("").map((c, i) => [c, i]));
+
+/**
+ * Decode Base58 string to bytes.
+ * @param {string} data
+ * @returns {Uint8Array}
+ */
+function decodeBase58(data) {
+  if (typeof data !== "string" || data.length === 0) throw new TypeError("invalid base58 string");
+
+  let bytes = [0];
+  for (const ch of data) {
+    const val = _B58_INDEX.get(ch);
+    if (val == null) throw new TypeError("invalid base58 character");
+
+    let carry = val;
+    for (let i = 0; i < bytes.length; i++) {
+      const x = bytes[i] * 58 + carry;
+      bytes[i] = x & 0xff;
+      carry = x >> 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+
+  // Deal with leading zeros
+  let leading = 0;
+  for (const ch of data) {
+    if (ch === "1") leading++;
+    else break;
+  }
+
+  const out = new Uint8Array(leading + bytes.length);
+  for (let i = 0; i < bytes.length; i++) out[out.length - 1 - i] = bytes[i];
+  return out;
+}
+
+/**
+ * Encode BytesLike as Base58.
+ * @param {BytesLike} data
+ * @returns {string}
+ */
+function encodeBase58(data) {
+  const bytes = arrayify(data);
+  let digits = [0];
+
+  for (const b of bytes) {
+    let carry = b;
+    for (let i = 0; i < digits.length; i++) {
+      const x = digits[i] * 256 + carry;
+      digits[i] = x % 58;
+      carry = (x / 58) | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = (carry / 58) | 0;
+    }
+  }
+
+  // Leading zeros
+  let leading = 0;
+  for (const b of bytes) {
+    if (b === 0) leading++;
+    else break;
+  }
+
+  let out = "1".repeat(leading);
+  for (let i = digits.length - 1; i >= 0; i--) out += _B58_ALPHABET[digits[i]];
+  return out;
+}
+
+/**
+ * Returns UTF-8 code points for a string.
+ * @param {string} str
+ * @returns {number[]}
+ */
+function toUtf8CodePoints(str) {
+  return Array.from(str).map((c) => c.codePointAt(0) || 0);
+}
+
+/**
+ * Solidity packed encoding.
+ * This is a complex helper in ethers.js; in QuantumCoin.js it is currently not implemented.
+ * @throws
+ */
+function solidityPacked() {
+  throw new Error("solidityPacked is not implemented in QuantumCoin.js yet");
+}
+function solidityPackedKeccak256() {
+  throw new Error("solidityPackedKeccak256 is not implemented in QuantumCoin.js yet");
+}
+function solidityPackedSha256() {
+  throw new Error("solidityPackedSha256 is not implemented in QuantumCoin.js yet");
+}
+
+module.exports = {
+  toUtf8String,
+  toUtf8Bytes,
+  toHex,
+  hexlify,
+  arrayify,
+  concat,
+  stripZerosLeft,
+  encodeBytes32String,
+  decodeBytes32String,
+  decodeBase58,
+  decodeBase64,
+  encodeBase58,
+  encodeBase64,
+  toUtf8CodePoints,
+  isHexString,
+  isBytesLike,
+  zeroPad,
+  zeroPadValue,
+  solidityPacked,
+  solidityPackedKeccak256,
+  solidityPackedSha256,
+  bytesToHex,
+  hexToBytes,
+};
+

package/src/utils/hashing.d.ts

@@ -0,0 +1,76 @@
+/**
+ * keccak256 hash of BytesLike.
+ * @param {string|Uint8Array} data
+ * @returns {string}
+ */
+export function keccak256(data: string | Uint8Array): string;
+/**
+ * sha256 hash of BytesLike.
+ * @param {string|Uint8Array} data
+ * @returns {string}
+ */
+export function sha256(data: string | Uint8Array): string;
+/**
+ * sha512 hash of BytesLike.
+ * @param {string|Uint8Array} data
+ * @returns {string}
+ */
+export function sha512(data: string | Uint8Array): string;
+/**
+ * ripemd160 hash of BytesLike.
+ * @param {string|Uint8Array} data
+ * @returns {string}
+ */
+export function ripemd160(data: string | Uint8Array): string;
+/**
+ * ethers-style id(text) => keccak256(utf8Bytes(text))
+ * @param {string} text
+ * @returns {string}
+ */
+export function id(text: string): string;
+/**
+ * Generate cryptographically strong random bytes.
+ * @param {number} length
+ * @returns {Uint8Array}
+ */
+export function randomBytes(length: number): Uint8Array;
+/**
+ * Compute HMAC over data.
+ * @param {string} algorithm
+ * @param {string|Uint8Array} key
+ * @param {string|Uint8Array} data
+ * @returns {string}
+ */
+export function computeHmac(algorithm: string, key: string | Uint8Array, data: string | Uint8Array): string;
+/**
+ * PBKDF2 (sync) helper returning hex string.
+ * @param {string|Uint8Array} password
+ * @param {string|Uint8Array} salt
+ * @param {number} iterations
+ * @param {number} keylen
+ * @param {string=} algorithm
+ * @returns {string}
+ */
+export function pbkdf2(password: string | Uint8Array, salt: string | Uint8Array, iterations: number, keylen: number, algorithm?: string | undefined): string;
+/**
+ * scrypt (async) helper returning hex string.
+ * @param {string|Uint8Array} password
+ * @param {string|Uint8Array} salt
+ * @param {number} N
+ * @param {number} r
+ * @param {number} p
+ * @param {number} dkLen
+ * @returns {Promise<string>}
+ */
+export function scrypt(password: string | Uint8Array, salt: string | Uint8Array, N: number, r: number, p: number, dkLen: number): Promise<string>;
+/**
+ * scrypt (sync) helper returning hex string.
+ * @param {string|Uint8Array} password
+ * @param {string|Uint8Array} salt
+ * @param {number} N
+ * @param {number} r
+ * @param {number} p
+ * @param {number} dkLen
+ * @returns {string}
+ */
+export function scryptSync(password: string | Uint8Array, salt: string | Uint8Array, N: number, r: number, p: number, dkLen: number): string;