@primuslabs/fhetransform-sdk 0.4.0

package/dist/core/system-contract-info.js

@@ -0,0 +1,41 @@
+import { FheErrorCode } from "./errors/error-codes.js";
+import { FheError } from "./errors/fhe-error.js";
+/**
+ * Returns the system contract addresses for a given blockchain chain ID.
+ * @param chainId - The blockchain chain ID
+ * @returns SystemContractInfo containing all required contract addresses
+ * @throws Error if the chain ID is not supported
+ */
+export function getSystemContractInfo(chainId) {
+    let info;
+    switch (chainId) {
+        case 31337n: // Anvil / Hardhat local development
+            info = {
+                aclContractAddress: "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
+                spaceBridgeConfigAddress: "0x8A791620dd6260079BF849Dc5567aDC3F2FdC318",
+                decryptionContractAddress: "0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82",
+                ciphertextVerificationAddress: "0x9A9f2CCfdE556A7E9Ff0848998Aa4a0CFD8863AE",
+            };
+            break;
+        case 56n: // BNB Smart Chain Mainnet
+            info = {
+                aclContractAddress: "0x3fE3B494Ae2d54fdee94C9fe60365024a44742AE",
+                spaceBridgeConfigAddress: "0x8914af6Bb24Cbff797Be208aBE388927C0FC0396",
+                decryptionContractAddress: "0x29873f805e66B39c28D394B213f712B7b2B52ba1",
+                ciphertextVerificationAddress: "0x9313191E3Eadc4C365d2043E8b7c03d73193D99A",
+            };
+            break;
+        case 97n: // BNB Smart Chain Testnet
+            info = {
+                aclContractAddress: "0x73d8e6Aa72DFD64ADcdF388411A6EE3F3CFa98B5",
+                spaceBridgeConfigAddress: "0xaF2e46a68AfBdf75026643f0ecFa4f355A3F22Ca",
+                decryptionContractAddress: "0x979A0Ccee4546dCDd0234db28cFf1A06DE2eb4d7",
+                ciphertextVerificationAddress: "0x26123D7a7406c3a1D54C15C8A129f2bdB55C4dec",
+            };
+            break;
+        default:
+            throw new FheError({ code: FheErrorCode.UnsupportedChain, message: `Unsupported system contract info for chainId: ${chainId.toString()}` });
+    }
+    return info;
+}
+//# sourceMappingURL=system-contract-info.js.map

package/dist/core/system-contract-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-contract-info.js","sourceRoot":"","sources":["../../src/core/system-contract-info.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAYjD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,IAAI,IAAwB,CAAC;IAE7B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM,EAAE,oCAAoC;YAC/C,IAAI,GAAG;gBACL,kBAAkB,EAAE,4CAAuD;gBAC3E,wBAAwB,EAAE,4CAAuD;gBACjF,yBAAyB,EAAE,4CAAuD;gBAClF,6BAA6B,EAAE,4CAAuD;aACvF,CAAC;YACF,MAAM;QAER,KAAK,GAAG,EAAE,0BAA0B;YAClC,IAAI,GAAG;gBACL,kBAAkB,EAAE,4CAAuD;gBAC3E,wBAAwB,EAAE,4CAAuD;gBACjF,yBAAyB,EAAE,4CAAuD;gBAClF,6BAA6B,EAAE,4CAAuD;aACvF,CAAC;YACF,MAAM;QAER,KAAK,GAAG,EAAE,0BAA0B;YAClC,IAAI,GAAG;gBACL,kBAAkB,EAAE,4CAAuD;gBAC3E,wBAAwB,EAAE,4CAAuD;gBACjF,yBAAyB,EAAE,4CAAuD;gBAClF,6BAA6B,EAAE,4CAAuD;aACvF,CAAC;YACF,MAAM;QAER;YACE,MAAM,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,gBAAgB,EAAE,OAAO,EAAE,iDAAiD,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;IAChJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/ttl-cache.d.ts

@@ -0,0 +1,81 @@
+/**
+ * A generic Time-To-Live (TTL) cache implementation.
+ * Caches data for a specified duration before automatically refreshing it.
+ *
+ * @template T - The type of data to be cached
+ *
+ * @example
+ * ```typescript
+ * const cache = new TTLCache<string[]>(5 * 60 * 1000); // 5 minutes TTL
+ * const data = await cache.get(async () => {
+ *   return await fetchDataFromSource();
+ * });
+ * ```
+ */
+export declare class TTLCache<T> {
+    /** Cached data, null if no data is cached or cache has been cleared */
+    private data;
+    /** Timestamp (in milliseconds) when the cache was last updated */
+    private timestamp;
+    /** Time-To-Live duration in milliseconds */
+    private readonly ttl;
+    /**
+     * Creates a new TTL cache instance.
+     *
+     * @param ttlMs - Time-To-Live in milliseconds. Defaults to 24 hours.
+     */
+    constructor(ttlMs?: number);
+    /**
+     * Retrieves cached data if it's still valid (within TTL), otherwise fetches fresh data.
+     *
+     * @param fetchFn - Async function that fetches fresh data when cache expires
+     * @param forceRefresh - If true, bypasses cache and forces a fresh fetch
+     * @returns The cached or freshly fetched data
+     *
+     * @example
+     * ```typescript
+     * // Normal usage - returns cached data if valid
+     * const result = await cache.get(() => fetchUserData());
+     *
+     * // Force refresh - bypasses cache
+     * const freshResult = await cache.get(() => fetchUserData(), true);
+     * ```
+     */
+    get(fetchFn: () => Promise<T>, forceRefresh?: boolean): Promise<T>;
+    /**
+     * Clears the cache, forcing the next `get()` call to fetch fresh data.
+     *
+     * @example
+     * ```typescript
+     * cache.clear(); // Next get() will fetch fresh data
+     * ```
+     */
+    clear(): void;
+    /**
+     * Checks if the cache has valid (non-expired) data.
+     *
+     * @returns True if cache contains valid data within TTL, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (cache.isValid()) {
+     *   // Cache hit - use cached data
+     * } else {
+     *   // Cache miss - need to fetch
+     * }
+     * ```
+     */
+    isValid(): boolean;
+    /**
+     * Gets the timestamp when the cache was last updated.
+     *
+     * @returns The timestamp in milliseconds, or 0 if cache is empty
+     */
+    getTimestamp(): number;
+    /**
+     * Gets the remaining time until cache expiration.
+     *
+     * @returns Milliseconds until cache expires, 0 if already expired or empty
+     */
+    getRemainingTTL(): number;
+}

package/dist/core/ttl-cache.js

@@ -0,0 +1,113 @@
+import { logger } from "./logger.js";
+/** Default TTL (Time-To-Live) for cache entries: 24 hours in milliseconds */
+const DEFAULT_TTL_CACHE_MS = 24 * 60 * 60 * 1000;
+/**
+ * A generic Time-To-Live (TTL) cache implementation.
+ * Caches data for a specified duration before automatically refreshing it.
+ *
+ * @template T - The type of data to be cached
+ *
+ * @example
+ * ```typescript
+ * const cache = new TTLCache<string[]>(5 * 60 * 1000); // 5 minutes TTL
+ * const data = await cache.get(async () => {
+ *   return await fetchDataFromSource();
+ * });
+ * ```
+ */
+export class TTLCache {
+    /** Cached data, null if no data is cached or cache has been cleared */
+    data = null;
+    /** Timestamp (in milliseconds) when the cache was last updated */
+    timestamp = 0;
+    /** Time-To-Live duration in milliseconds */
+    ttl;
+    /**
+     * Creates a new TTL cache instance.
+     *
+     * @param ttlMs - Time-To-Live in milliseconds. Defaults to 24 hours.
+     */
+    constructor(ttlMs = DEFAULT_TTL_CACHE_MS) {
+        this.ttl = ttlMs;
+    }
+    /**
+     * Retrieves cached data if it's still valid (within TTL), otherwise fetches fresh data.
+     *
+     * @param fetchFn - Async function that fetches fresh data when cache expires
+     * @param forceRefresh - If true, bypasses cache and forces a fresh fetch
+     * @returns The cached or freshly fetched data
+     *
+     * @example
+     * ```typescript
+     * // Normal usage - returns cached data if valid
+     * const result = await cache.get(() => fetchUserData());
+     *
+     * // Force refresh - bypasses cache
+     * const freshResult = await cache.get(() => fetchUserData(), true);
+     * ```
+     */
+    async get(fetchFn, forceRefresh = false) {
+        const now = Date.now();
+        // Check if cache is valid: not force refreshed, data exists, and within TTL
+        if (!forceRefresh && this.data !== null && (now - this.timestamp) < this.ttl) {
+            logger.debug("[TTLCache.get] Use cached:", this.data, this.timestamp);
+            return this.data;
+        }
+        // Cache expired or force refresh requested - fetch fresh data
+        this.data = await fetchFn();
+        this.timestamp = now;
+        logger.debug("[TTLCache.get] New fetched:", this.data, this.timestamp);
+        return this.data;
+    }
+    /**
+     * Clears the cache, forcing the next `get()` call to fetch fresh data.
+     *
+     * @example
+     * ```typescript
+     * cache.clear(); // Next get() will fetch fresh data
+     * ```
+     */
+    clear() {
+        this.data = null;
+        this.timestamp = 0;
+    }
+    /**
+     * Checks if the cache has valid (non-expired) data.
+     *
+     * @returns True if cache contains valid data within TTL, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (cache.isValid()) {
+     *   // Cache hit - use cached data
+     * } else {
+     *   // Cache miss - need to fetch
+     * }
+     * ```
+     */
+    isValid() {
+        const now = Date.now();
+        return this.data !== null && (now - this.timestamp) < this.ttl;
+    }
+    /**
+     * Gets the timestamp when the cache was last updated.
+     *
+     * @returns The timestamp in milliseconds, or 0 if cache is empty
+     */
+    getTimestamp() {
+        return this.timestamp;
+    }
+    /**
+     * Gets the remaining time until cache expiration.
+     *
+     * @returns Milliseconds until cache expires, 0 if already expired or empty
+     */
+    getRemainingTTL() {
+        if (this.data === null)
+            return 0;
+        const now = Date.now();
+        const remaining = this.ttl - (now - this.timestamp);
+        return Math.max(0, remaining);
+    }
+}
+//# sourceMappingURL=ttl-cache.js.map

package/dist/core/ttl-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/core/ttl-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,6EAA6E;AAC7E,MAAM,oBAAoB,GAAW,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,QAAQ;IACnB,uEAAuE;IAC/D,IAAI,GAAa,IAAI,CAAC;IAE9B,kEAAkE;IAC1D,SAAS,GAAW,CAAC,CAAC;IAE9B,4CAA4C;IAC3B,GAAG,CAAS;IAE7B;;;;OAIG;IACH,YAAY,QAAgB,oBAAoB;QAC9C,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,GAAG,CAAC,OAAyB,EAAE,eAAwB,KAAK;QAChE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,4EAA4E;QAC5E,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7E,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YACtE,OAAO,IAAI,CAAC,IAAI,CAAC;QACnB,CAAC;QAED,8DAA8D;QAC9D,IAAI,CAAC,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC;QACrB,MAAM,CAAC,KAAK,CAAC,6BAA6B,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,OAAO;QACL,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;IACjE,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/core/tx-error-parser.d.ts

@@ -0,0 +1,40 @@
+import { ethers } from "ethers";
+/**
+ * Parses and extracts human-readable error messages from contract revert data.
+ * Supports multiple ABIs and provides fallback error handling.
+ */
+export declare class ErrorParser {
+    private interfaces;
+    /**
+     * Adds an ABI to the parser for error decoding.
+     * @param abi - An ethers Interface or ABI definition
+     * @returns The current instance for method chaining
+     */
+    addAbi(abi: ethers.Interface | ethers.InterfaceAbi): this;
+    /**
+     * Attempts to parse an error from hex-encoded revert data.
+     * @param errorData - The hex string of the revert data (e.g., from error.data)
+     * @returns Parsed error name and formatted arguments, or null if no match
+     */
+    parseError(errorData: string): {
+        name: string;
+        args: string;
+    } | null;
+    /**
+     * Extracts a human-readable error message from an error object.
+     * Tries to parse revert data first, then falls back to error properties.
+     * @param error - The error object from a failed transaction
+     * @returns A formatted error message string
+     */
+    getMessage(error: any): string;
+    /**
+     * Wraps an error handler that logs the original error and throws a formatted message.
+     * Useful as a catch callback in promise chains.
+     *
+     * @example
+     * ```ts
+     * contract.function().catch(errorParser.catch);
+     * ```
+     */
+    catch: (error: any) => never;
+}

package/dist/core/tx-error-parser.js

@@ -0,0 +1,83 @@
+import { Interface } from "ethers";
+import { logger } from "./logger.js";
+import { FheErrorCode } from "./errors/error-codes.js";
+import { FheError } from "./errors/fhe-error.js";
+/**
+ * Parses and extracts human-readable error messages from contract revert data.
+ * Supports multiple ABIs and provides fallback error handling.
+ */
+export class ErrorParser {
+    interfaces = [];
+    /**
+     * Adds an ABI to the parser for error decoding.
+     * @param abi - An ethers Interface or ABI definition
+     * @returns The current instance for method chaining
+     */
+    addAbi(abi) {
+        this.interfaces.push(abi instanceof Interface ? abi : new Interface(abi));
+        return this;
+    }
+    /**
+     * Attempts to parse an error from hex-encoded revert data.
+     * @param errorData - The hex string of the revert data (e.g., from error.data)
+     * @returns Parsed error name and formatted arguments, or null if no match
+     */
+    parseError(errorData) {
+        for (const iface of this.interfaces) {
+            try {
+                const parsed = iface.parseError(errorData);
+                if (parsed) {
+                    // Format arguments for display: bigints as strings, others as JSON
+                    const argsStr = Object.values(parsed.args)
+                        .map((v) => (typeof v === "bigint" ? v.toString() : JSON.stringify(v)))
+                        .join(", ");
+                    return { name: parsed.name, args: argsStr };
+                }
+            }
+            catch {
+                // Ignore parsing errors and try the next interface
+                continue;
+            }
+        }
+        return null;
+    }
+    /**
+     * Extracts a human-readable error message from an error object.
+     * Tries to parse revert data first, then falls back to error properties.
+     * @param error - The error object from a failed transaction
+     * @returns A formatted error message string
+     */
+    getMessage(error) {
+        // Attempt to parse custom error from revert data
+        if (error?.data && error.data !== "0x") {
+            const parsed = this.parseError(error.data);
+            if (parsed) {
+                return `${parsed.name}(${parsed.args})`;
+            }
+        }
+        // Fallback to standard error properties
+        return error?.reason || error?.shortMessage || error?.message || "Transaction failed";
+    }
+    /**
+     * Wraps an error handler that logs the original error and throws a formatted message.
+     * Useful as a catch callback in promise chains.
+     *
+     * @example
+     * ```ts
+     * contract.function().catch(errorParser.catch);
+     * ```
+     */
+    catch = (error) => {
+        logger.error("Original error:", error);
+        const message = this.getMessage(error);
+        const hasRevertData = typeof error?.data === "string" && error.data !== "0x";
+        const parsed = hasRevertData ? this.parseError(error.data) : null;
+        throw new FheError({
+            code: hasRevertData ? FheErrorCode.TransactionReverted : FheErrorCode.ContractCallFailed,
+            message,
+            context: parsed ? { details: parsed } : undefined,
+            cause: error,
+        });
+    };
+}
+//# sourceMappingURL=tx-error-parser.js.map

package/dist/core/tx-error-parser.js.map

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

package/dist/core/utils.d.ts

@@ -0,0 +1,62 @@
+export declare function logErrorAndThrow(message: string): void;
+/**
+ * Sleep for the specified number of milliseconds
+ *
+ * @param ms - Number of milliseconds to sleep
+ * @returns Promise that resolves after the specified delay
+ */
+export declare function sleepMs(ms: number): Promise<void>;
+/**
+ * Gets environment variable value (Node.js only)
+ * Supports only Node.js (process.env) and falls back gracefully in browser
+ *
+ * @param key - Environment variable name
+ * @returns Value or undefined if not found
+ *
+ * @example
+ * const rpcUrl = getEnv('RPC_URL');
+ */
+export declare function getEnv(key: string): string | undefined;
+/**
+ * Gets required environment variable, throws if not found
+ *
+ * @param key - Environment variable name
+ * @returns Value
+ * @throws Error if environment variable is not set
+ *
+ * @example
+ * const rpcUrl = requireEnv('RPC_URL');
+ */
+export declare function requireEnv(key: string): string;
+/**
+ * Creates a lazy-loaded value that initializes only once on first access
+ *
+ * @param factory - Async function that produces the value
+ * @returns A function that returns a Promise resolving to the cached value
+ *
+ * @example
+ * const getData = lazy(async () => {
+ *   const result = await fetchData();
+ *   return result;
+ * });
+ *
+ * const data = await getData(); // First call executes factory
+ * const cached = await getData(); // Returns cached value
+ */
+export declare function lazy<T>(factory: () => Promise<T>): () => Promise<T>;
+/**
+ * Concatenates multiple Uint8Array instances into a single Uint8Array
+ * Uses Buffer.concat in Node.js for better performance, falls back to manual
+ * concatenation in browser environments
+ *
+ * @param inputs - Array of Uint8Array instances to concatenate
+ * @returns A new Uint8Array containing all input data concatenated
+ */
+export declare function concatUint8Arrays(inputs: Uint8Array[]): Uint8Array;
+/**
+ * Asserts that a given string is a valid URL.
+ * Throws an error if the URL is invalid.
+ * @param url - The URL string to validate
+ * @throws Error if the URL is invalid
+ */
+export declare function assertIsValidUrl(url: string): void;

package/dist/core/utils.js

@@ -0,0 +1,143 @@
+import { logger } from "./logger.js";
+import { FheErrorCode } from "./errors/error-codes.js";
+import { FheError } from "./errors/fhe-error.js";
+export function logErrorAndThrow(message) {
+    logger.error(message);
+    throw new FheError({ code: FheErrorCode.Internal, message });
+}
+/**
+ * Sleep for the specified number of milliseconds
+ *
+ * @param ms - Number of milliseconds to sleep
+ * @returns Promise that resolves after the specified delay
+ */
+export function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Gets environment variable value (Node.js only)
+ * Supports only Node.js (process.env) and falls back gracefully in browser
+ *
+ * @param key - Environment variable name
+ * @returns Value or undefined if not found
+ *
+ * @example
+ * const rpcUrl = getEnv('RPC_URL');
+ */
+export function getEnv(key) {
+    // Check if running in Node.js environment
+    if (typeof process !== 'undefined' && process.env) {
+        return process.env[key];
+    }
+    return undefined;
+}
+/**
+ * Gets required environment variable, throws if not found
+ *
+ * @param key - Environment variable name
+ * @returns Value
+ * @throws Error if environment variable is not set
+ *
+ * @example
+ * const rpcUrl = requireEnv('RPC_URL');
+ */
+export function requireEnv(key) {
+    const value = getEnv(key);
+    if (!value) {
+        logger.error(`Required environment variable not set: ${key}`);
+        throw new FheError({ code: FheErrorCode.InvalidConfig, message: `Environment variable ${key} is required but not set` });
+    }
+    return value;
+}
+/**
+ * Creates a lazy-loaded value that initializes only once on first access
+ *
+ * @param factory - Async function that produces the value
+ * @returns A function that returns a Promise resolving to the cached value
+ *
+ * @example
+ * const getData = lazy(async () => {
+ *   const result = await fetchData();
+ *   return result;
+ * });
+ *
+ * const data = await getData(); // First call executes factory
+ * const cached = await getData(); // Returns cached value
+ */
+export function lazy(factory) {
+    let hasValue = false;
+    let value = undefined;
+    let promise = null;
+    return async () => {
+        if (hasValue) {
+            logger.trace('Lazy value already resolved, returning cached');
+            return value;
+        }
+        if (promise !== null) {
+            logger.trace('Lazy value currently being resolved, waiting for existing promise');
+            return promise;
+        }
+        logger.debug('Lazy value not resolved, executing factory');
+        promise = factory().then(result => {
+            value = result;
+            hasValue = true;
+            promise = null;
+            logger.debug('Lazy value resolved successfully');
+            return result;
+        }).catch((error) => {
+            logger.error('Lazy value resolution failed:', error);
+            promise = null;
+            throw error;
+        });
+        return promise;
+    };
+}
+/**
+ * Concatenates multiple Uint8Array instances into a single Uint8Array
+ * Uses Buffer.concat in Node.js for better performance, falls back to manual
+ * concatenation in browser environments
+ *
+ * @param inputs - Array of Uint8Array instances to concatenate
+ * @returns A new Uint8Array containing all input data concatenated
+ */
+export function concatUint8Arrays(inputs) {
+    if (inputs.length === 0) {
+        logger.trace('concatUint8Arrays called with empty array');
+        return new Uint8Array(0);
+    }
+    const isNode = typeof Buffer !== 'undefined' && typeof Buffer.concat === 'function';
+    // Node.js environment - use native Buffer.concat for performance
+    if (isNode) {
+        logger.trace(`Concatenating ${inputs.length} arrays using Buffer.concat (Node.js)`);
+        const buffers = inputs.map(arr => Buffer.from(arr));
+        const result = new Uint8Array(Buffer.concat(buffers));
+        logger.trace(`Concatenated ${inputs.length} arrays into ${result.length} bytes`);
+        return result;
+    }
+    // Browser environment - manual concatenation
+    logger.trace(`Concatenating ${inputs.length} arrays manually (browser)`);
+    const totalLength = inputs.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of inputs) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    logger.trace(`Concatenated ${inputs.length} arrays into ${result.length} bytes`);
+    return result;
+}
+/**
+ * Asserts that a given string is a valid URL.
+ * Throws an error if the URL is invalid.
+ * @param url - The URL string to validate
+ * @throws Error if the URL is invalid
+ */
+export function assertIsValidUrl(url) {
+    try {
+        new URL(url);
+    }
+    catch (error) {
+        throw new FheError({ code: FheErrorCode.InvalidArgument, message: `Invalid URL: "${url}"`, cause: error });
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/core/utils.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export { FheType, Operator } from "./core/fhe-type.js";
+export type { HandleLike, Plaintext, UnverifiedEncryptData } from "./core/fhe-type.js";
+export type { Address, Bytes, Bytes32Hex, Bytes65Hex, Bytes65HexNo0x, BytesHex, BytesHexNo0x, EvenLen, Hex0x, HexNo0x, } from "./core/primitives.js";
+export { FheTransformSDK } from "./sdk/fhetransform-sdk.js";
+export type { FheTransformConfig } from "./sdk/fhetransform-sdk-b.js";
+export { PermitService } from "./sdk/permit-service.js";
+export type { GetPermitOption, GetPermitResult } from "./sdk/permit-service.js";
+export { ConvertToken } from "./contract/convert-token.js";
+export type { FinalizeUnshieldOptions, FinalizeUnshieldResult, ShieldOptions, ShieldResult, UnshieldAndFinalizeOptions, UnshieldOptions, UnshieldResult, } from "./contract/convert-token.js";
+export { Token, TokenBase } from "./contract/token.js";
+export type { TransferOptions, TransferResult } from "./contract/token.js";
+export type { ErrorCallbacks, FinalizeUnshieldCallbacks, ShieldCallbacks, TransferCallbacks, UnshieldAndFinalizeCallbacks, UnshieldCallbacks, } from "./contract/callbacks.js";
+export type { RawLog, TransactionReceipt, TransactionResult } from "./contract/transaction.js";
+export type { EncryptOptions, EncryptParameters, EncryptPayload, EncryptPayloadItem, EncryptResult, } from "./jazz/encrypt.js";
+export type { PublicDecryptOptions, PublicDecryptParameters, PublicDecryptPayload, PublicDecryptResult, } from "./jazz/public-decrypt.js";
+export type { UserDecryptInput, UserDecryptOptions, UserDecryptParameters, UserDecryptPayload, UserDecryptResult, } from "./jazz/user-decrypt.js";
+export type { JazzOnProgressArgs, JazzProcessOptions } from "./jazz/types/common.js";
+export type { SignedDecryptionPermit } from "./jazz/permit.js";
+export { FheTransformSDKEvents } from "./core/event.js";
+export type { FheTransformSDKEvent, FheTransformSDKEventListener, FheTransformSDKEventType, } from "./core/event.js";
+export { ADDRESS_ZERO, areEqualAddresses, assertChecksumAddress, ChecksumAddressError, isChecksumAddress, isValidAddress, isZeroAddress, toChecksumAddress, toChecksumAddresses, toChecksumAddressesFiltered, toChecksumAddressesSafe, } from "./core/address.js";
+export type { ChecksumAddress } from "./core/address.js";
+export { buildSetChainKeysArgs, CHAINS, getChainKey } from "./core/chain.js";
+export type { ChainInfo } from "./core/chain.js";
+export { getSystemContractInfo } from "./core/system-contract-info.js";
+export type { SystemContractInfo } from "./core/system-contract-info.js";
+export { getSignerAddressInfo } from "./core/signer-address-info.js";
+export type { SignerAddressInfo } from "./core/signer-address-info.js";
+export { estimateFheFee } from "./core/estimate.js";
+export type { FheFeeDetails, FheFeeEstimate } from "./core/estimate.js";
+export { setAxiosAuth } from "./core/auth.js";
+export type { Auth, AuthApiKeyCookie, AuthApiKeyHeader, AuthBearerToken, AuthType } from "./core/auth.js";
+export { ErrorParser } from "./core/tx-error-parser.js";
+export { FheError } from "./core/errors/fhe-error.js";
+export type { FheErrorOptions, FheErrorPayload, SanitizedCause } from "./core/errors/fhe-error.js";
+export { FheErrorCode } from "./core/errors/error-codes.js";
+export type { FheErrorCatalogEntry, FheErrorContext } from "./core/errors/error-catalog.js";
+export { formatMessage, getErrorCatalogEntry } from "./core/errors/error-catalog.js";
+export { getErrorCode, getErrorMessage, getErrorRetryPolicy, isFheError, toFheError, withFheError, } from "./core/errors/error-utils.js";
+export type { ErrorRetryPolicy } from "./core/errors/error-utils.js";