@primuslabs/fhetransform-sdk 0.4.0

package/dist/core/address.d.ts

@@ -0,0 +1,118 @@
+import { FheError } from './errors/fhe-error.js';
+/**
+ * Branded type for EIP-55 checksummed Ethereum addresses.
+ * Use `toChecksumAddress()` to create, never cast directly.
+ */
+export type ChecksumAddress = string & {
+    readonly __brand: unique symbol;
+};
+export declare const ADDRESS_ZERO: ChecksumAddress;
+/**
+ * Check if a string is a valid EIP-55 checksum address.
+ *
+ * @param address - The address to validate
+ * @returns `true` if the address is valid and checksummed
+ *
+ * @example
+ * isChecksumAddress('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266') // true
+ * isChecksumAddress('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266') // false
+ */
+export declare function isChecksumAddress(address: string): address is ChecksumAddress;
+/**
+ * Check if a string is a valid Ethereum address (with or without checksum).
+ *
+ * @param address - The address to validate
+ * @returns `true` if the address is valid
+ *
+ * @example
+ * isValidAddress('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266') // true
+ * isValidAddress('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266') // true
+ * isValidAddress('0xinvalid') // false
+ */
+export declare function isValidAddress(address: string): boolean;
+/**
+ * Assert that a string is a valid checksum address.
+ * Throws an error with a descriptive message if validation fails.
+ *
+ * @param address - The address to validate
+ * @param context - Optional context for error message (e.g., 'contractAddress')
+ * @throws {ChecksumAddressError} If the address is invalid
+ *
+ * @example
+ * assertChecksumAddress('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
+ * assertChecksumAddress(address, 'userAddress');
+ */
+export declare function assertChecksumAddress(address: string, context?: string): asserts address is ChecksumAddress;
+/**
+ * Convert an Ethereum address to EIP-55 checksum format.
+ *
+ * @param address - The address to convert (with or without 0x prefix)
+ * @returns The checksummed address as `ChecksumAddress`
+ * @throws {ChecksumAddressError} If the address is invalid
+ *
+ * @example
+ * toChecksumAddress('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266')
+ * // => '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+ */
+export declare function toChecksumAddress(address: string): ChecksumAddress;
+/**
+ * Convert multiple addresses to checksum format.
+ *
+ * @param addresses - Array of addresses to convert
+ * @returns Array of checksummed addresses
+ * @throws {ChecksumAddressError} If any address is invalid
+ *
+ * @example
+ * toChecksumAddresses(['0xf39fd6e...', '0x70997970...'])
+ */
+export declare function toChecksumAddresses(addresses: string[]): ChecksumAddress[];
+/**
+ * Safely convert addresses to checksum format.
+ * Invalid addresses return `null` instead of throwing.
+ *
+ * @param addresses - Array of addresses to convert
+ * @returns Array of checksummed addresses or `null` for invalid ones
+ *
+ * @example
+ * toChecksumAddressesSafe(['0xf39fd6e...', '0xinvalid', '0x70997970...'])
+ * // => ['0xf39Fd6e...', null, '0x70997970...']
+ */
+export declare function toChecksumAddressesSafe(addresses: string[]): (ChecksumAddress | null)[];
+/**
+ * Convert addresses to checksum format and filter out invalid ones.
+ *
+ * @param addresses - Array of addresses to convert
+ * @returns Array of valid checksummed addresses only
+ *
+ * @example
+ * toChecksumAddressesFiltered(['0xf39fd6e...', '0xinvalid', '0x70997970...'])
+ * // => ['0xf39Fd6e...', '0x70997970...']
+ */
+export declare function toChecksumAddressesFiltered(addresses: string[]): ChecksumAddress[];
+/**
+ * Compare two addresses for equality (case-insensitive).
+ *
+ * @param address1 - First address
+ * @param address2 - Second address
+ * @returns `true` if both addresses are valid and equal
+ *
+ * @example
+ * areEqualAddresses(
+ *   '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ *   '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
+ * ) // true
+ */
+export declare function areEqualAddresses(address1: string, address2: string): boolean;
+/**
+ * Check if an address is the zero address.
+ *
+ * @param address - The address to check
+ * @returns `true` if the address is the zero address
+ */
+export declare function isZeroAddress(address: string): boolean;
+/**
+ * Custom error for checksum address validation failures.
+ */
+export declare class ChecksumAddressError extends FheError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/core/address.js

@@ -0,0 +1,200 @@
+import { getAddress, isAddress } from 'ethers';
+import { FheErrorCode } from './errors/error-codes.js';
+import { FheError } from './errors/fhe-error.js';
+// ============================================================================
+// Constants
+// ============================================================================
+export const ADDRESS_ZERO = '0x0000000000000000000000000000000000000000';
+// ============================================================================
+// Validation
+// ============================================================================
+/**
+ * Check if a string is a valid EIP-55 checksum address.
+ *
+ * @param address - The address to validate
+ * @returns `true` if the address is valid and checksummed
+ *
+ * @example
+ * isChecksumAddress('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266') // true
+ * isChecksumAddress('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266') // false
+ */
+export function isChecksumAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return false;
+    }
+    try {
+        return getAddress(address) === address;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a string is a valid Ethereum address (with or without checksum).
+ *
+ * @param address - The address to validate
+ * @returns `true` if the address is valid
+ *
+ * @example
+ * isValidAddress('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266') // true
+ * isValidAddress('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266') // true
+ * isValidAddress('0xinvalid') // false
+ */
+export function isValidAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return false;
+    }
+    try {
+        return isAddress(address);
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Assertions
+// ============================================================================
+/**
+ * Assert that a string is a valid checksum address.
+ * Throws an error with a descriptive message if validation fails.
+ *
+ * @param address - The address to validate
+ * @param context - Optional context for error message (e.g., 'contractAddress')
+ * @throws {ChecksumAddressError} If the address is invalid
+ *
+ * @example
+ * assertChecksumAddress('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
+ * assertChecksumAddress(address, 'userAddress');
+ */
+export function assertChecksumAddress(address, context) {
+    if (!isChecksumAddress(address)) {
+        const prefix = context ? `[${context}] ` : '';
+        throw new ChecksumAddressError(`${prefix}Invalid checksum address: ${address}`);
+    }
+}
+// ============================================================================
+// Conversion
+// ============================================================================
+/**
+ * Convert an Ethereum address to EIP-55 checksum format.
+ *
+ * @param address - The address to convert (with or without 0x prefix)
+ * @returns The checksummed address as `ChecksumAddress`
+ * @throws {ChecksumAddressError} If the address is invalid
+ *
+ * @example
+ * toChecksumAddress('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266')
+ * // => '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+ */
+export function toChecksumAddress(address) {
+    if (!address || typeof address !== 'string') {
+        throw new ChecksumAddressError('Address is required');
+    }
+    try {
+        return getAddress(address);
+    }
+    catch (error) {
+        throw new ChecksumAddressError(`Invalid address: ${address}`, { cause: error });
+    }
+}
+/**
+ * Convert multiple addresses to checksum format.
+ *
+ * @param addresses - Array of addresses to convert
+ * @returns Array of checksummed addresses
+ * @throws {ChecksumAddressError} If any address is invalid
+ *
+ * @example
+ * toChecksumAddresses(['0xf39fd6e...', '0x70997970...'])
+ */
+export function toChecksumAddresses(addresses) {
+    return addresses.map((addr) => toChecksumAddress(addr));
+}
+/**
+ * Safely convert addresses to checksum format.
+ * Invalid addresses return `null` instead of throwing.
+ *
+ * @param addresses - Array of addresses to convert
+ * @returns Array of checksummed addresses or `null` for invalid ones
+ *
+ * @example
+ * toChecksumAddressesSafe(['0xf39fd6e...', '0xinvalid', '0x70997970...'])
+ * // => ['0xf39Fd6e...', null, '0x70997970...']
+ */
+export function toChecksumAddressesSafe(addresses) {
+    return addresses.map((addr) => {
+        try {
+            return toChecksumAddress(addr);
+        }
+        catch {
+            return null;
+        }
+    });
+}
+/**
+ * Convert addresses to checksum format and filter out invalid ones.
+ *
+ * @param addresses - Array of addresses to convert
+ * @returns Array of valid checksummed addresses only
+ *
+ * @example
+ * toChecksumAddressesFiltered(['0xf39fd6e...', '0xinvalid', '0x70997970...'])
+ * // => ['0xf39Fd6e...', '0x70997970...']
+ */
+export function toChecksumAddressesFiltered(addresses) {
+    return toChecksumAddressesSafe(addresses).filter((addr) => addr !== null);
+}
+// ============================================================================
+// Comparison
+// ============================================================================
+/**
+ * Compare two addresses for equality (case-insensitive).
+ *
+ * @param address1 - First address
+ * @param address2 - Second address
+ * @returns `true` if both addresses are valid and equal
+ *
+ * @example
+ * areEqualAddresses(
+ *   '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ *   '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
+ * ) // true
+ */
+export function areEqualAddresses(address1, address2) {
+    if (!address1 || !address2) {
+        return false;
+    }
+    try {
+        return getAddress(address1).toLowerCase() === getAddress(address2).toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if an address is the zero address.
+ *
+ * @param address - The address to check
+ * @returns `true` if the address is the zero address
+ */
+export function isZeroAddress(address) {
+    try {
+        return getAddress(address) === ADDRESS_ZERO;
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Custom error for checksum address validation failures.
+ */
+export class ChecksumAddressError extends FheError {
+    constructor(message, options) {
+        super({ code: FheErrorCode.InvalidAddress, message, cause: options?.cause });
+        this.name = 'ChecksumAddressError';
+    }
+}
+//# sourceMappingURL=address.js.map

package/dist/core/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/core/address.ts"],"names":[],"mappings":"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"}

package/dist/core/auth.d.ts

@@ -0,0 +1,68 @@
+import { InternalAxiosRequestConfig } from "axios";
+/**
+ * Supported authentication methods for API requests.
+ */
+export type AuthType = 'BearerToken' | 'ApiKeyHeader' | 'ApiKeyCookie';
+/**
+ * Bearer Token authentication.
+ * Adds an `Authorization: Bearer <token>` header to the request.
+ */
+export type AuthBearerToken = {
+    type: 'BearerToken';
+    /** The Bearer token string. */
+    token: string;
+};
+/**
+ * Custom header authentication.
+ * Adds a custom header (default: `x-api-key`) with the provided API key value.
+ */
+export type AuthApiKeyHeader = {
+    type: 'ApiKeyHeader';
+    /** The header name. Defaults to `x-api-key` if not specified. */
+    header?: string;
+    /** The API key value to send in the header. */
+    value: string;
+};
+/**
+ * Custom cookie authentication.
+ * Sets a cookie (default: `x-api-key`) with the provided API key value.
+ * In browser environments, sets `document.cookie`; in Node.js, adds a `Cookie` header.
+ */
+export type AuthApiKeyCookie = {
+    type: 'ApiKeyCookie';
+    /** The cookie name. Defaults to `x-api-key` if not specified. */
+    cookie?: string;
+    /** The API key value to set in the cookie. */
+    value: string;
+};
+/**
+ * Union type of all supported authentication configurations.
+ */
+export type Auth = AuthBearerToken | AuthApiKeyHeader | AuthApiKeyCookie;
+/**
+ * Applies the specified authentication method to an Axios request configuration.
+ *
+ * Supported authentication methods:
+ * - `BearerToken`: Adds `Authorization: Bearer <token>` header.
+ * - `ApiKeyHeader`: Adds a custom header (default: `x-api-key`) with the API key.
+ * - `ApiKeyCookie`: Sets a cookie (default: `x-api-key`) with the API key.
+ *
+ * If no authentication is provided, the request configuration is returned unchanged.
+ *
+ * @param config - The Axios request configuration to modify.
+ * @param auth - Optional authentication configuration.
+ * @returns The modified Axios request configuration.
+ *
+ * @example
+ * ```typescript
+ * // Bearer Token
+ * setAxiosAuth(config, { type: 'BearerToken', token: 'jwt-token' });
+ *
+ * // Custom Header
+ * setAxiosAuth(config, { type: 'ApiKeyHeader', header: 'api-key', value: 'key-123' });
+ *
+ * // Custom Cookie
+ * setAxiosAuth(config, { type: 'ApiKeyCookie', cookie: 'api_key', value: 'key-123' });
+ * ```
+ */
+export declare function setAxiosAuth(config: InternalAxiosRequestConfig, auth?: Auth): InternalAxiosRequestConfig;

package/dist/core/auth.js

@@ -0,0 +1,58 @@
+import { isNonEmptyString } from "./string.js";
+/**
+ * Applies the specified authentication method to an Axios request configuration.
+ *
+ * Supported authentication methods:
+ * - `BearerToken`: Adds `Authorization: Bearer <token>` header.
+ * - `ApiKeyHeader`: Adds a custom header (default: `x-api-key`) with the API key.
+ * - `ApiKeyCookie`: Sets a cookie (default: `x-api-key`) with the API key.
+ *
+ * If no authentication is provided, the request configuration is returned unchanged.
+ *
+ * @param config - The Axios request configuration to modify.
+ * @param auth - Optional authentication configuration.
+ * @returns The modified Axios request configuration.
+ *
+ * @example
+ * ```typescript
+ * // Bearer Token
+ * setAxiosAuth(config, { type: 'BearerToken', token: 'jwt-token' });
+ *
+ * // Custom Header
+ * setAxiosAuth(config, { type: 'ApiKeyHeader', header: 'api-key', value: 'key-123' });
+ *
+ * // Custom Cookie
+ * setAxiosAuth(config, { type: 'ApiKeyCookie', cookie: 'api_key', value: 'key-123' });
+ * ```
+ */
+export function setAxiosAuth(config, auth) {
+    if (!auth)
+        return config;
+    const headers = config.headers;
+    switch (auth.type) {
+        case 'BearerToken': {
+            headers.Authorization = `Bearer ${auth.token}`;
+            break;
+        }
+        case 'ApiKeyHeader': {
+            const headerName = isNonEmptyString(auth.header) ? auth.header : 'x-api-key';
+            headers[headerName] = auth.value;
+            break;
+        }
+        case 'ApiKeyCookie': {
+            const cookieName = isNonEmptyString(auth.cookie) ? auth.cookie : 'x-api-key';
+            if (typeof window !== 'undefined') {
+                // Browser environment: set cookie via document.cookie
+                document.cookie = `${cookieName}=${auth.value}; path=/; SameSite=Lax; Secure;`;
+                config.withCredentials = true;
+            }
+            else {
+                // Node.js environment: set Cookie header
+                headers.Cookie = `${cookieName}=${auth.value};`;
+            }
+            break;
+        }
+    }
+    return config;
+}
+//# sourceMappingURL=auth.js.map

package/dist/core/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/core/auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA+C/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAkC,EAClC,IAAW;IAEX,IAAI,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC;IAEzB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAE/B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,OAAO,CAAC,aAAa,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/C,MAAM;QACR,CAAC;QAED,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;YAC7E,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;YACjC,MAAM;QACR,CAAC;QAED,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;YAC7E,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;gBAClC,sDAAsD;gBACtD,QAAQ,CAAC,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,KAAK,iCAAiC,CAAC;gBAC/E,MAAM,CAAC,eAAe,GAAG,IAAI,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACN,yCAAyC;gBACzC,OAAO,CAAC,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC;YAClD,CAAC;YACD,MAAM;QACR,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/bytes.d.ts

@@ -0,0 +1,48 @@
+import { Bytes32Hex, BytesHexNo0x } from "./primitives.js";
+/**
+ * Converts a hex string to a Uint8Array.
+ * Supports both prefixed (0x) and non-prefixed hex strings.
+ * @param hexString - Hex string (e.g., "0x1234" or "1234")
+ * @returns Uint8Array representation of the hex string
+ * @throws Error if the hex string has an odd number of digits or contains non-hex characters
+ */
+export declare const fromHexString: (hexString: string) => Uint8Array;
+/**
+ * Converts a Uint8Array to a hex string with a "0x" prefix.
+ * @param byteArray - The byte array to convert
+ * @returns Hex string with "0x" prefix (e.g., "0x1234")
+ */
+export declare function bytesToHex(byteArray: Uint8Array): `0x${string}`;
+/**
+ * Converts a Uint8Array to a hex string without the "0x" prefix.
+ *
+ * @param bytes - The byte array to convert. Returns `""` if `undefined` or empty.
+ * @returns A lowercase hex string with even length (2 chars per byte), without the "0x" prefix.
+ *
+ * @example
+ * bytesToHexNo0x(new Uint8Array([0x48, 0x65])) // "4865"
+ * bytesToHexNo0x(new Uint8Array([0x0a]))       // "0a"
+ * bytesToHexNo0x(undefined)                    // ""
+ * bytesToHexNo0x(new Uint8Array([]))           // ""
+ */
+export declare function bytesToHexNo0x(bytes: Uint8Array | undefined): BytesHexNo0x;
+/**
+ * Converts a Uint8Array to a BigInt.
+ * @param byteArray - The byte array to convert
+ * @returns BigInt representation of the byte array
+ */
+export declare function bytesToBigInt(byteArray: Uint8Array): bigint;
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array.
+ * @param parts - Variable number of Uint8Arrays to concatenate
+ * @returns A new Uint8Array containing all input arrays concatenated in order
+ */
+export declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
+/**
+ * Validates and casts a string to the Bytes32Hex type.
+ * Ensures the string is a 32-byte hex string with a "0x" prefix (66 characters total).
+ * @param value - The value to validate and cast
+ * @returns The validated Bytes32Hex string
+ * @throws Error if the value is not a valid 32-byte hex string
+ */
+export declare function toBytes32Hex(value: unknown): Bytes32Hex;

package/dist/core/bytes.js

@@ -0,0 +1,117 @@
+import { FheErrorCode } from "./errors/error-codes.js";
+import { FheError } from "./errors/fhe-error.js";
+/** Nibble lookup table for fast hex decoding (avoids per-byte parseInt). */
+const HEX_VALUE = {
+    "0": 0, "1": 1, "2": 2, "3": 3, "4": 4, "5": 5, "6": 6, "7": 7,
+    "8": 8, "9": 9, "a": 10, "b": 11, "c": 12, "d": 13, "e": 14, "f": 15,
+    "A": 10, "B": 11, "C": 12, "D": 13, "E": 14, "F": 15,
+};
+/**
+ * Converts a hex string to a Uint8Array.
+ * Supports both prefixed (0x) and non-prefixed hex strings.
+ * @param hexString - Hex string (e.g., "0x1234" or "1234")
+ * @returns Uint8Array representation of the hex string
+ * @throws Error if the hex string has an odd number of digits or contains non-hex characters
+ */
+export const fromHexString = (hexString) => {
+    // Remove the "0x" prefix if present
+    const cleaned = hexString.replace(/^(0x)/, "");
+    if (cleaned.length === 0)
+        return new Uint8Array();
+    // Each byte requires exactly two hex digits; reject malformed input instead
+    // of silently changing its value (e.g. "0x123" -> 0x0123).
+    if (cleaned.length % 2 !== 0) {
+        throw new FheError({ code: FheErrorCode.InvalidHex, message: `Invalid hex string: "${hexString}" (odd number of hex digits)` });
+    }
+    if (!/^[0-9a-fA-F]+$/.test(cleaned)) {
+        throw new FheError({ code: FheErrorCode.InvalidHex, message: `Invalid hex string: "${hexString}" (contains non-hex characters)` });
+    }
+    const result = new Uint8Array(cleaned.length / 2);
+    for (let i = 0; i < cleaned.length; i += 2) {
+        result[i / 2] = (HEX_VALUE[cleaned[i]] << 4) | HEX_VALUE[cleaned[i + 1]];
+    }
+    return result;
+};
+/**
+ * Converts a Uint8Array to a hex string with a "0x" prefix.
+ * @param byteArray - The byte array to convert
+ * @returns Hex string with "0x" prefix (e.g., "0x1234")
+ */
+export function bytesToHex(byteArray) {
+    if (!byteArray || byteArray.length === 0) {
+        return "0x";
+    }
+    let hex = "";
+    for (const byte of byteArray) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    return `0x${hex}`;
+}
+/**
+ * Converts a Uint8Array to a hex string without the "0x" prefix.
+ *
+ * @param bytes - The byte array to convert. Returns `""` if `undefined` or empty.
+ * @returns A lowercase hex string with even length (2 chars per byte), without the "0x" prefix.
+ *
+ * @example
+ * bytesToHexNo0x(new Uint8Array([0x48, 0x65])) // "4865"
+ * bytesToHexNo0x(new Uint8Array([0x0a]))       // "0a"
+ * bytesToHexNo0x(undefined)                    // ""
+ * bytesToHexNo0x(new Uint8Array([]))           // ""
+ */
+export function bytesToHexNo0x(bytes) {
+    if (!bytes || bytes.length === 0) {
+        return '';
+    }
+    let hex = '';
+    for (const byte of bytes) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/**
+ * Converts a Uint8Array to a BigInt.
+ * @param byteArray - The byte array to convert
+ * @returns BigInt representation of the byte array
+ */
+export function bytesToBigInt(byteArray) {
+    if (!byteArray || byteArray.length === 0) {
+        return 0n;
+    }
+    let hex = "";
+    for (const byte of byteArray) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    return BigInt(`0x${hex}`);
+}
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array.
+ * @param parts - Variable number of Uint8Arrays to concatenate
+ * @returns A new Uint8Array containing all input arrays concatenated in order
+ */
+export function concatBytes(...parts) {
+    // Calculate total length of the resulting array
+    const totalLength = parts.reduce((sum, part) => sum + part.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+/**
+ * Validates and casts a string to the Bytes32Hex type.
+ * Ensures the string is a 32-byte hex string with a "0x" prefix (66 characters total).
+ * @param value - The value to validate and cast
+ * @returns The validated Bytes32Hex string
+ * @throws Error if the value is not a valid 32-byte hex string
+ */
+export function toBytes32Hex(value) {
+    // Check if the value is a valid 0x-prefixed 64-character hex string
+    if (typeof value === "string" && /^0x[a-fA-F0-9]{64}$/.test(value)) {
+        return value;
+    }
+    throw new FheError({ code: FheErrorCode.InvalidHex, message: `Invalid Bytes32Hex: ${value}` });
+}
+//# sourceMappingURL=bytes.js.map

package/dist/core/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../src/core/bytes.ts"],"names":[],"mappings":"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"}