@primuslabs/fhetransform-sdk 0.4.0

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

@@ -0,0 +1,138 @@
+/**
+ * Configuration options for the CacheManager.
+ */
+export interface CacheOptions {
+    /** Base name for IndexedDB storage */
+    baseName?: string;
+    /** Store name for IndexedDB storage */
+    storeName?: string;
+    /** IndexedDB database name */
+    dbName?: string;
+    /** Storage directory for Node.js environment */
+    baseDir?: string;
+}
+/**
+ * Cache entry structure containing data and timestamp metadata.
+ */
+export interface CacheEntry {
+    /** The cached data as a string */
+    data: string;
+    /** Unix timestamp (seconds) when the entry was created */
+    timestamp: number;
+}
+/**
+ * CacheManager - Universal caching layer supporting both binary and string data.
+ *
+ * Features:
+ * - Binary and string data storage
+ * - TTL-based expiration checks
+ * - Lazy storage initialization
+ * - Cross-platform support (Node.js filesystem, browser IndexedDB)
+ * - Batch operations (list, clear, delete)
+ */
+export declare class CacheManager {
+    private options;
+    private storage;
+    /**
+     * Creates a new CacheManager instance.
+     * @param options - Cache configuration options
+     */
+    constructor(options?: CacheOptions);
+    /**
+     * Saves data to the cache.
+     * Binary data (Uint8Array) is stored raw with separate metadata.
+     * String data is stored as a CacheEntry with timestamp.
+     *
+     * @param key - Cache key
+     * @param data - Data to cache (Uint8Array or string)
+     * @returns Promise that resolves when save is complete
+     * @throws Error if storage operation fails
+     */
+    save(key: string, data: Uint8Array | string): Promise<void>;
+    /**
+     * Loads data from the cache, returning either binary or string data.
+     * Checks raw storage first for binary data, then falls back to CacheEntry/string.
+     *
+     * @param key - Cache key
+     * @returns Cached data as Uint8Array or string, or null if not found
+     */
+    load(key: string): Promise<Uint8Array | string | null>;
+    /**
+     * Loads string data from the cache.
+     * Convenience method for string-only access.
+     *
+     * @param key - Cache key
+     * @returns Cached string data, or null if not found or not a string
+     */
+    loadString(key: string): Promise<string | null>;
+    /**
+     * Loads binary data from the cache.
+     * Convenience method for binary-only access.
+     *
+     * @param key - Cache key
+     * @returns Cached binary data as Uint8Array, or null if not found
+     */
+    loadBytes(key: string): Promise<Uint8Array | null>;
+    /**
+     * Determines whether the cache should be refreshed (missing or expired).
+     *
+     * @param key - The cache key to check
+     * @param ttl - Time-to-live in seconds
+     * @returns true if cache should be refreshed, false if still valid
+     */
+    shouldRefresh(key: string, ttl: number): Promise<boolean>;
+    /**
+     * Deletes a specific cache entry and its associated metadata.
+     *
+     * @param key - Cache key to delete
+     * @returns Promise that resolves when deletion is complete
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists all cache keys matching an optional prefix.
+     *
+     * @param base - Optional prefix to filter keys
+     * @returns Array of cache keys
+     */
+    listKeys(base?: string): Promise<string[]>;
+    /**
+     * Clears all cache entries with an optional prefix.
+     * Deletes both main entries and their metadata counterparts.
+     *
+     * @param base - Optional prefix to filter keys for clearing
+     * @returns Promise that resolves when clear is complete
+     */
+    clear(base?: string): Promise<void>;
+    /**
+     * Lazy-initializes and returns the storage instance.
+     * Storage is created once and reused for all operations.
+     *
+     * @returns The initialized Storage instance
+     * @throws Error if storage initialization fails
+     */
+    private getStorage;
+    /**
+     * Initializes the storage backend based on the runtime environment.
+     * Uses #runtime to select the appropriate driver (Node.js fs or browser IndexedDB).
+     *
+     * @param options - Cache configuration options
+     * @returns Configured Storage instance
+     * @throws Error if driver creation fails
+     */
+    private initStorage;
+    /**
+     * Type guard for validating CacheEntry objects.
+     *
+     * @param value - Value to check
+     * @returns true if value is a valid CacheEntry
+     */
+    private isCacheEntry;
+    /**
+     * Checks if a timestamp has expired relative to the maximum age (in seconds).
+     *
+     * @param timestamp - Unix timestamp (seconds) when entry was created
+     * @param maxAge - Maximum age in seconds
+     * @returns true if the entry has expired
+     */
+    private isExpired;
+}

package/dist/core/cache-manager.js

@@ -0,0 +1,440 @@
+import { createStorage } from 'unstorage';
+import { logger } from './logger.js';
+import { createCacheDriver, getDbBaseNameScope } from '#runtime';
+// ============================================================================
+// CacheManager Class
+// ============================================================================
+/**
+ * CacheManager - Universal caching layer supporting both binary and string data.
+ *
+ * Features:
+ * - Binary and string data storage
+ * - TTL-based expiration checks
+ * - Lazy storage initialization
+ * - Cross-platform support (Node.js filesystem, browser IndexedDB)
+ * - Batch operations (list, clear, delete)
+ */
+export class CacheManager {
+    options;
+    storage = null;
+    /**
+     * Creates a new CacheManager instance.
+     * @param options - Cache configuration options
+     */
+    constructor(options = {}) {
+        this.options = { ...options };
+        logger.debug('[CacheManager] Instance created', { options: this.options });
+    }
+    /**
+     * Saves data to the cache.
+     * Binary data (Uint8Array) is stored raw with separate metadata.
+     * String data is stored as a CacheEntry with timestamp.
+     *
+     * @param key - Cache key
+     * @param data - Data to cache (Uint8Array or string)
+     * @returns Promise that resolves when save is complete
+     * @throws Error if storage operation fails
+     */
+    async save(key, data) {
+        // Get storage instance (lazy init)
+        const storage = await this.getStorage();
+        const timestamp = Math.floor(Date.now() / 1000);
+        const isBinary = data instanceof Uint8Array;
+        logger.debug('[CacheManager.save] Saving cache entry', {
+            key,
+            type: isBinary ? 'binary' : 'string',
+            size: data.length,
+        });
+        try {
+            if (isBinary) {
+                // Store raw binary data and its metadata separately
+                logger.trace('[CacheManager.save] Storing binary data with metadata', { key });
+                await storage.setItemRaw(key, data);
+                await storage.setItem(`${key}.meta`, { timestamp });
+            }
+            else {
+                // Store string data as a CacheEntry
+                logger.trace('[CacheManager.save] Storing string data as CacheEntry', { key });
+                await storage.setItem(key, { data, timestamp });
+            }
+            logger.debug('[CacheManager.save] Cache saved successfully', { key, size: data.length });
+        }
+        catch (error) {
+            logger.error('[CacheManager.save] Failed to save cache', {
+                key,
+                type: isBinary ? 'binary' : 'string',
+                error: error.message,
+                stack: error.stack,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Loads data from the cache, returning either binary or string data.
+     * Checks raw storage first for binary data, then falls back to CacheEntry/string.
+     *
+     * @param key - Cache key
+     * @returns Cached data as Uint8Array or string, or null if not found
+     */
+    async load(key) {
+        const storage = await this.getStorage();
+        logger.debug('[CacheManager.load] Loading cache entry', { key });
+        try {
+            // Attempt to read raw binary data first
+            const rawData = await storage.getItemRaw(key);
+            if (rawData instanceof Uint8Array) {
+                logger.debug('[CacheManager.load] Cache loaded (binary)', {
+                    key,
+                    size: rawData.length,
+                });
+                return rawData;
+            }
+            // Attempt to read as CacheEntry or plain string
+            const entry = await storage.getItem(key);
+            if (!entry) {
+                logger.debug('[CacheManager.load] Cache miss', { key });
+                return null;
+            }
+            // Return data field if in CacheEntry format
+            if (this.isCacheEntry(entry)) {
+                logger.debug('[CacheManager.load] Cache loaded (CacheEntry)', {
+                    key,
+                    dataLength: entry.data.length,
+                });
+                return entry.data;
+            }
+            // Return directly if in plain string format (backward compatibility)
+            if (typeof entry === 'string') {
+                logger.debug('[CacheManager.load] Cache loaded (string)', {
+                    key,
+                    size: entry.length,
+                });
+                return entry;
+            }
+            logger.warn('[CacheManager.load] Invalid cache format', { key, type: typeof entry });
+            return null;
+        }
+        catch (error) {
+            logger.error('[CacheManager.load] Failed to load cache', {
+                key,
+                error: error.message,
+                stack: error.stack,
+            });
+            return null;
+        }
+    }
+    /**
+     * Loads string data from the cache.
+     * Convenience method for string-only access.
+     *
+     * @param key - Cache key
+     * @returns Cached string data, or null if not found or not a string
+     */
+    async loadString(key) {
+        const storage = await this.getStorage();
+        logger.debug('[CacheManager.loadString] Loading string cache', { key });
+        try {
+            const entry = await storage.getItem(key);
+            if (!entry) {
+                logger.debug('[CacheManager.loadString] Cache miss', { key });
+                return null;
+            }
+            if (this.isCacheEntry(entry)) {
+                logger.debug('[CacheManager.loadString] Cache loaded (CacheEntry)', {
+                    key,
+                    dataLength: entry.data.length,
+                });
+                return entry.data;
+            }
+            if (typeof entry === 'string') {
+                logger.debug('[CacheManager.loadString] Cache loaded (string)', {
+                    key,
+                    size: entry.length,
+                });
+                return entry;
+            }
+            logger.warn('[CacheManager.loadString] Invalid format for string', {
+                key,
+                type: typeof entry,
+            });
+            return null;
+        }
+        catch (error) {
+            logger.error('[CacheManager.loadString] Failed to load string cache', {
+                key,
+                error: error.message,
+                stack: error.stack,
+            });
+            return null;
+        }
+    }
+    /**
+     * Loads binary data from the cache.
+     * Convenience method for binary-only access.
+     *
+     * @param key - Cache key
+     * @returns Cached binary data as Uint8Array, or null if not found
+     */
+    async loadBytes(key) {
+        const storage = await this.getStorage();
+        logger.debug('[CacheManager.loadBytes] Loading binary cache', { key });
+        try {
+            const rawData = await storage.getItemRaw(key);
+            if (rawData instanceof Uint8Array) {
+                logger.debug('[CacheManager.loadBytes] Cache loaded (binary)', {
+                    key,
+                    size: rawData.length,
+                });
+                return rawData;
+            }
+            logger.debug('[CacheManager.loadBytes] Binary cache miss', { key });
+            return null;
+        }
+        catch (error) {
+            logger.error('[CacheManager.loadBytes] Failed to load binary cache', {
+                key,
+                error: error.message,
+                stack: error.stack,
+            });
+            return null;
+        }
+    }
+    /**
+     * Determines whether the cache should be refreshed (missing or expired).
+     *
+     * @param key - The cache key to check
+     * @param ttl - Time-to-live in seconds
+     * @returns true if cache should be refreshed, false if still valid
+     */
+    async shouldRefresh(key, ttl) {
+        const storage = await this.getStorage();
+        logger.debug('[CacheManager.shouldRefresh] Checking cache freshness', {
+            key,
+            ttlSeconds: ttl,
+        });
+        try {
+            // Check metadata for raw binary data
+            const meta = await storage.getItem(`${key}.meta`);
+            if (meta && typeof meta === 'object' && 'timestamp' in meta) {
+                const expired = this.isExpired(meta.timestamp, ttl);
+                logger.trace('[CacheManager.shouldRefresh] Cache freshness check (meta)', {
+                    key,
+                    expired,
+                    age: Math.floor(Date.now() / 1000) - meta.timestamp,
+                });
+                return expired;
+            }
+            // Check direct storage data (backward compatibility)
+            const data = await storage.getItem(key);
+            if (data) {
+                if (this.isCacheEntry(data)) {
+                    const expired = this.isExpired(data.timestamp, ttl);
+                    logger.trace('[CacheManager.shouldRefresh] Cache freshness check (CacheEntry)', {
+                        key,
+                        expired,
+                        age: Math.floor(Date.now() / 1000) - data.timestamp,
+                    });
+                    return expired;
+                }
+                // Has data but no timestamp - treat as needing refresh
+                logger.warn('[CacheManager.shouldRefresh] Data without timestamp, needs refresh', {
+                    key,
+                });
+                return true;
+            }
+            logger.trace('[CacheManager.shouldRefresh] Cache miss, needs refresh', { key });
+            return true;
+        }
+        catch (error) {
+            logger.error('[CacheManager.shouldRefresh] Failed to check freshness', {
+                key,
+                error: error.message,
+                stack: error.stack,
+            });
+            return true; // On error, assume refresh needed
+        }
+    }
+    /**
+     * Deletes a specific cache entry and its associated metadata.
+     *
+     * @param key - Cache key to delete
+     * @returns Promise that resolves when deletion is complete
+     */
+    async delete(key) {
+        const storage = await this.getStorage();
+        logger.debug('[CacheManager.delete] Deleting cache entry', { key });
+        try {
+            await Promise.all([
+                storage.removeItem(key),
+                storage.removeItem(`${key}.meta`),
+            ]);
+            logger.trace('[CacheManager.delete] Cache deleted successfully', { key });
+        }
+        catch (error) {
+            logger.error('[CacheManager.delete] Failed to delete cache', {
+                key,
+                error: error.message,
+                stack: error.stack,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Lists all cache keys matching an optional prefix.
+     *
+     * @param base - Optional prefix to filter keys
+     * @returns Array of cache keys
+     */
+    async listKeys(base) {
+        const storage = await this.getStorage();
+        logger.debug('[CacheManager.listKeys] Listing cache keys', {
+            prefix: base || '(root)',
+        });
+        try {
+            const _prefix = getDbBaseNameScope();
+            const _base = `${_prefix}${base}`;
+            const keys = await storage.getKeys(base === undefined ? base : _base);
+            logger.debug('[CacheManager.listKeys] Keys listed successfully', {
+                prefix: base || '(root)',
+                count: keys.length,
+                keys: keys.length > 0 ? keys.slice(0, 10) : [], // Log first 10 to avoid bloat
+            });
+            return keys.map((key) => {
+                return key.startsWith(_prefix) ? key.slice(_prefix.length) : key;
+            });
+        }
+        catch (error) {
+            logger.error('[CacheManager.listKeys] Failed to list keys', {
+                prefix: base || '(root)',
+                error: error.message,
+                stack: error.stack,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Clears all cache entries with an optional prefix.
+     * Deletes both main entries and their metadata counterparts.
+     *
+     * @param base - Optional prefix to filter keys for clearing
+     * @returns Promise that resolves when clear is complete
+     */
+    async clear(base) {
+        const storage = await this.getStorage();
+        logger.debug('[CacheManager.clear] Clearing cache', {
+            prefix: base || '(root)',
+        });
+        try {
+            const keys = await this.listKeys(base);
+            logger.debug('[CacheManager.clear] Found keys to clear', {
+                prefix: base || '(root)',
+                count: keys.length,
+                keys,
+            });
+            // Delete all keys and their metadata in parallel
+            const deletePromises = keys.flatMap((key) => [
+                storage.removeItem(key),
+                storage.removeItem(`${key}.meta`),
+            ]);
+            await Promise.all(deletePromises);
+            logger.debug('[CacheManager.clear] Cache cleared successfully', {
+                prefix: base || '(root)',
+                keysRemoved: keys.length,
+            });
+        }
+        catch (error) {
+            logger.error('[CacheManager.clear] Failed to clear cache', {
+                prefix: base || '(root)',
+                error: error.message,
+                stack: error.stack,
+            });
+            throw error;
+        }
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    /**
+     * Lazy-initializes and returns the storage instance.
+     * Storage is created once and reused for all operations.
+     *
+     * @returns The initialized Storage instance
+     * @throws Error if storage initialization fails
+     */
+    async getStorage() {
+        if (this.storage === null) {
+            logger.debug('[CacheManager.getStorage] Initializing storage (lazy)');
+            this.storage = await this.initStorage(this.options);
+        }
+        return this.storage;
+    }
+    /**
+     * Initializes the storage backend based on the runtime environment.
+     * Uses #runtime to select the appropriate driver (Node.js fs or browser IndexedDB).
+     *
+     * @param options - Cache configuration options
+     * @returns Configured Storage instance
+     * @throws Error if driver creation fails
+     */
+    async initStorage(options) {
+        logger.debug('[CacheManager.initStorage] Creating storage backend', { options });
+        try {
+            const driver = await createCacheDriver(options);
+            logger.trace('[CacheManager.initStorage] Cache driver created', {
+                driverType: typeof driver,
+            });
+            const storage = createStorage({ driver });
+            logger.debug('[CacheManager.initStorage] Storage initialized successfully');
+            return storage;
+        }
+        catch (error) {
+            logger.error('[CacheManager.initStorage] Failed to initialize storage', {
+                options,
+                error: error.message,
+                stack: error.stack,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Type guard for validating CacheEntry objects.
+     *
+     * @param value - Value to check
+     * @returns true if value is a valid CacheEntry
+     */
+    isCacheEntry(value) {
+        const isValid = value && typeof value === 'object' &&
+            'data' in value && typeof value.data === 'string' &&
+            'timestamp' in value && typeof value.timestamp === 'number';
+        if (!isValid && value && typeof value === 'object') {
+            logger.trace('[CacheManager.isCacheEntry] Invalid CacheEntry format', {
+                hasData: 'data' in value,
+                hasTimestamp: 'timestamp' in value,
+                dataType: typeof value.data,
+                timestampType: typeof value.timestamp,
+            });
+        }
+        return isValid;
+    }
+    /**
+     * Checks if a timestamp has expired relative to the maximum age (in seconds).
+     *
+     * @param timestamp - Unix timestamp (seconds) when entry was created
+     * @param maxAge - Maximum age in seconds
+     * @returns true if the entry has expired
+     */
+    isExpired(timestamp, maxAge) {
+        const now = Math.floor(Date.now() / 1000);
+        const age = now - timestamp;
+        const expired = age >= maxAge;
+        if (expired) {
+            logger.trace('[CacheManager.isExpired] Entry expired', {
+                age,
+                maxAge,
+                expired: true,
+            });
+        }
+        return expired;
+    }
+}
+//# sourceMappingURL=cache-manager.js.map

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

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

package/dist/core/chain.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Chain information for supported blockchain networks.
+ */
+export interface ChainInfo {
+    /** Blockchain chain ID (uint256) */
+    chainId: bigint;
+    /** Mapped chain key used in handles (uint8) */
+    chainKey: number;
+    /** Human-readable network name */
+    name: string;
+}
+/**
+ * List of supported blockchain networks with their chain ID to chain key mappings.
+ * Chain key is a compact identifier used in handle generation.
+ */
+export declare const CHAINS: readonly ChainInfo[];
+/**
+ * Map chain key to chain ID for quick lookup
+ * Created as a Map for O(1) lookup performance
+ */
+export declare const chainKeyToChainIdMap: Map<number, bigint>;
+/**
+ * Map chain ID to chain key for reverse lookup
+ * Useful for validation and debugging
+ */
+export declare const chainIdToChainKeyMap: Map<bigint, number>;
+/**
+ * Converts a blockchain chain ID to its corresponding chain key.
+ * @param chainId - Blockchain chain ID (e.g., 1n for Ethereum Mainnet)
+ * @returns The mapped chain key (uint8) used in handle generation
+ * @throws Error if the chain ID is not supported
+ */
+export declare function getChainKey(chainId: bigint): number;
+/**
+ * Builds arguments for setting chain mappings in a smart contract.
+ * @returns An object containing arrays of chain IDs and their corresponding chain keys
+ */
+export declare function buildSetChainKeysArgs(): {
+    chainIds: bigint[];
+    chainKeys: number[];
+};