Cryptographic Utilities

import { 
  bytesToHex, hexToBytes, concatBytes, copyBytes, equalBytes,
  bytesToUtf8, utf8ToBytes, asciiToBytes, isBytes, ensureBytes
} from "@noble/curves/utils";

/**
 * Converts byte array to hexadecimal string
 * @param bytes - Byte array to convert
 * @returns Lowercase hexadecimal string without 0x prefix
 */
function bytesToHex(bytes: Uint8Array): string;

/**
 * Converts hexadecimal string to byte array
 * @param hex - Hex string (with or without 0x prefix)
 * @returns Byte array representation
 */
function hexToBytes(hex: string): Uint8Array;

/**
 * Concatenates multiple byte arrays into one
 * @param arrays - Variable number of byte arrays to concatenate
 * @returns Single concatenated byte array
 */
function concatBytes(...arrays: Uint8Array[]): Uint8Array;

/**
 * Creates a copy of a byte array
 * @param bytes - Byte array to copy
 * @returns New byte array with same contents
 */
function copyBytes(bytes: Uint8Array): Uint8Array;

/**
 * Compares two byte arrays for equality in constant time
 * @param a - First byte array
 * @param b - Second byte array
 * @returns True if arrays are equal, false otherwise
 */
function equalBytes(a: Uint8Array, b: Uint8Array): boolean;

/**
 * Converts UTF-8 string to byte array
 * @param str - UTF-8 string to convert
 * @returns Byte array representation
 */
function utf8ToBytes(str: string): Uint8Array;

/**
 * Converts byte array to UTF-8 string
 * @param bytes - Byte array to convert
 * @returns UTF-8 string representation
 */
function bytesToUtf8(bytes: Uint8Array): string;

/**
 * Converts ASCII string to byte array
 * @param ascii - ASCII string to convert
 * @returns Byte array representation
 */
function asciiToBytes(ascii: string): Uint8Array;

/**
 * Type guard to check if value is a Uint8Array
 * @param a - Value to check
 * @returns True if value is Uint8Array
 */
function isBytes(a: unknown): a is Uint8Array;

/**
 * Ensures input is a byte array with optional length validation
 * @param title - Description for error messages
 * @param hex - Input that should be converted to bytes
 * @param expectedLength - Optional expected byte length
 * @returns Validated byte array
 */
function ensureBytes(title: string, hex: Hex, expectedLength?: number): Uint8Array;

import { bytesToHex, hexToBytes, concatBytes, utf8ToBytes } from "@noble/curves/utils";

// Hex conversion
const bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
const hex = bytesToHex(bytes); // "48656c6c6f"
const backToBytes = hexToBytes(hex); // Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f])

// Concatenation
const part1 = utf8ToBytes("Hello");
const part2 = utf8ToBytes(" World");
const combined = concatBytes(part1, part2); // "Hello World" in bytes

import { 
  bytesToNumberBE, bytesToNumberLE, numberToBytesBE, numberToBytesLE,
  numberToVarBytesBE, numberToHexUnpadded, hexToNumber
} from "@noble/curves/utils";

/**
 * Converts byte array to big-endian number
 * @param bytes - Byte array to convert
 * @returns BigInt representation
 */
function bytesToNumberBE(bytes: Uint8Array): bigint;

/**
 * Converts byte array to little-endian number  
 * @param bytes - Byte array to convert
 * @returns BigInt representation
 */
function bytesToNumberLE(bytes: Uint8Array): bigint;

/**
 * Converts number to big-endian byte array with fixed length
 * @param n - Number to convert
 * @param len - Target byte array length
 * @returns Big-endian byte array
 */
function numberToBytesBE(n: number | bigint, len: number): Uint8Array;

/**
 * Converts number to little-endian byte array with fixed length
 * @param n - Number to convert  
 * @param len - Target byte array length
 * @returns Little-endian byte array
 */
function numberToBytesLE(n: number | bigint, len: number): Uint8Array;

/**
 * Converts number to big-endian byte array with minimal length
 * @param n - Number to convert
 * @returns Big-endian byte array without leading zeros
 */
function numberToVarBytesBE(n: number | bigint): Uint8Array;

/**
 * Converts number to hexadecimal string without padding
 * @param num - Number to convert
 * @returns Hex string without leading zeros or 0x prefix
 */
function numberToHexUnpadded(num: number | bigint): string;

/**
 * Converts hexadecimal string to number
 * @param hex - Hex string (with or without 0x prefix)
 * @returns BigInt representation
 */
function hexToNumber(hex: string): bigint;

import { numberToBytesBE, bytesToNumberBE, numberToHexUnpadded } from "@noble/curves/utils";

// Number to bytes conversion
const num = 0x12345678n;
const bytes = numberToBytesBE(num, 8); // 8-byte big-endian representation
const backToNum = bytesToNumberBE(bytes); // 0x12345678n

// Hex conversion
const hex = numberToHexUnpadded(255); // "ff"

import { 
  inRange, aInRange, abool, abytes, anumber, validateObject, isHash
} from "@noble/curves/utils";

/**
 * Checks if number is within specified range
 * @param n - Number to check
 * @param min - Minimum value (inclusive)
 * @param max - Maximum value (exclusive)
 * @returns True if n is in range [min, max)
 */
function inRange(n: bigint, min: bigint, max: bigint): boolean;

/**
 * Asserts that number is within specified range
 * @param title - Description for error message
 * @param n - Number to check
 * @param min - Minimum value (inclusive)
 * @param max - Maximum value (exclusive)
 * @throws Error if n is not in range
 */
function aInRange(title: string, n: bigint, min: bigint, max: bigint): void;

/**
 * Asserts that value is a boolean
 * @param title - Description for error message
 * @param value - Value to check
 * @throws Error if value is not boolean
 */
function abool(title: string, value: boolean): void;

/**
 * Asserts that value is a Uint8Array
 * @param title - Description for error message
 * @param value - Value to check
 * @param length - Optional expected length
 * @throws Error if value is not Uint8Array or wrong length
 */
function abytes(title: string, value: Uint8Array, length?: number): void;

/**
 * Asserts that value is a number
 * @param title - Description for error message
 * @param value - Value to check
 * @throws Error if value is not a number
 */
function anumber(title: string, value: number): void;

/**
 * Validates object structure using schema
 * @param obj - Object to validate
 * @param validators - Schema of validation functions
 * @param optValidators - Optional field validators
 * @returns Validated object
 */
function validateObject<T extends Record<string, any>>(
  obj: any,
  validators: Record<string, (v: any) => any>,
  optValidators?: Record<string, (v: any) => any>
): T;

/**
 * Checks if value implements hash function interface
 * @param val - Value to check
 * @returns True if value has hash function properties
 */
function isHash(val: any): val is CHash;

import { bitLen, bitGet, bitSet, bitMask } from "@noble/curves/utils";

/**
 * Gets bit length of a number
 * @param n - Number to measure
 * @returns Number of bits needed to represent n
 */
function bitLen(n: bigint): number;

/**
 * Gets bit value at specific position
 * @param n - Number to read from
 * @param pos - Bit position (0 = least significant)
 * @returns Bit value (0n or 1n)
 */
function bitGet(n: bigint, pos: number): bigint;

/**
 * Sets bit value at specific position
 * @param n - Number to modify
 * @param pos - Bit position (0 = least significant)
 * @param value - Bit value to set
 * @returns Modified number
 */
function bitSet(n: bigint, pos: number, value: boolean): bigint;

/**
 * Creates bit mask with n bits set
 * @param n - Number of bits to set
 * @returns Bitmask with n least significant bits set
 */
function bitMask(n: number): bigint;

import { randomBytes } from "@noble/curves/utils";

/**
 * Generates cryptographically secure random bytes
 * @param bytesLength - Number of bytes to generate (default: 32)
 * @returns Random byte array
 */
function randomBytes(bytesLength?: number): Uint8Array;

import { createHmacDrbg } from "@noble/curves/utils";

/**
 * Creates HMAC-based deterministic random bit generator
 * @param hashLen - Hash function output length
 * @param qByteLen - Output byte length
 * @param hmacFn - HMAC function
 * @returns DRBG function
 */
function createHmacDrbg<T>(
  hashLen: number,
  qByteLen: number,
  hmacFn: HmacFnSync
): (seed: Uint8Array, k?: Uint8Array, v?: Uint8Array) => () => T;

import { memoized, notImplemented } from "@noble/curves/utils";

/**
 * Creates memoized version of a function
 * @param fn - Function to memoize
 * @returns Memoized function that caches results
 */
function memoized<T extends object, R, O extends any[]>(
  fn: (obj: T, ...args: O) => R
): (obj: T, ...args: O) => R;

/**
 * Throws "not implemented" error
 * @throws Error indicating feature is not implemented
 */
function notImplemented(): never;

import { 
  randomBytes, ensureBytes, numberToBytesLE, bytesToNumberLE
} from "@noble/curves/utils";

// Re-exported from main utils - same functionality as abstract/utils
// but may have optimizations for specific curve implementations

import { 
  bytesToHex, hexToBytes, bytesToNumberBE, numberToBytesBE,
  randomBytes, ensureBytes
} from "@noble/curves/abstract/utils";

// Same API as main utils module
// These are the core utilities used internally by abstract curve implementations

import { getHash, createCurve } from "@noble/curves/_shortw_utils";

/**
 * Gets hash configuration for curve implementations
 * @param hash - Hash function to wrap
 * @returns Hash configuration object
 */
function getHash(hash: CHash): { hash: CHash };

/**
 * Creates curve implementation with hash function (deprecated)
 * @param curveDef - Curve definition parameters
 * @param defHash - Default hash function
 * @returns Curve function with create method
 * @deprecated Use weierstrass() from abstract/weierstrass instead
 */
function createCurve(curveDef: CurveDef, defHash: CHash): CurveFnWithCreate;

// Type definitions
type CurveDef = Readonly<Omit<CurveType, 'hash'>>;
type CurveFnWithCreate = CurveFn & { 
  create: (hash: CHash) => CurveFn;
};

// Input types
type Hex = Uint8Array | string; // Flexible hex input
type PrivKey = Hex | bigint; // Private key input

// Hash function interfaces
interface CHash {
  (message: Uint8Array): Uint8Array;
  blockLen: number; // Hash block size in bytes
  outputLen: number; // Hash output size in bytes
  create(): any; // Hash instance creator
}

interface FHash {
  (message: Uint8Array | string): Uint8Array;
}

// HMAC function type
type HmacFnSync = (key: Uint8Array, ...messages: Uint8Array[]) => Uint8Array;

import { ensureBytes, hexToBytes, utf8ToBytes } from "@noble/curves/utils";

// Handle flexible input types
function processInput(input: Hex): Uint8Array {
  return typeof input === 'string' 
    ? hexToBytes(input)
    : ensureBytes('input', input);
}

// Validate byte lengths
const key = ensureBytes('private key', userInput, 32); // Ensure 32 bytes

import { 
  numberToBytesBE, bytesToNumberBE, 
  numberToHexUnpadded, hexToNumber 
} from "@noble/curves/utils";

// Convert between formats
const num = 0x1234567890abcdefn;
const bytes = numberToBytesBE(num, 8);  // 8-byte big-endian
const hex = numberToHexUnpadded(num);   // "1234567890abcdef"
const backToNum = hexToNumber(hex);     // 0x1234567890abcdefn

import { equalBytes } from "@noble/curves/utils";

// Constant-time comparison
const hash1 = new Uint8Array([1, 2, 3, 4]);
const hash2 = new Uint8Array([1, 2, 3, 4]);
const isEqual = equalBytes(hash1, hash2); // true, computed in constant time