@monygroupcorp/micro-web3 0.1.0

package/src/services/ContractCache.js

@@ -0,0 +1,348 @@
+class ContractCache {
+    constructor(eventBus) {
+        if (!eventBus) {
+            throw new Error('ContractCache requires an eventBus instance.');
+        }
+        this.eventBus = eventBus;
+        // Cache storage: Map<key, {value, expiresAt, accessCount}>
+        this.cache = new Map();
+        
+        // Cache statistics
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            invalidations: 0,
+            sets: 0
+        };
+        
+        // Default TTL per method type (in milliseconds)
+        this.defaultTTLs = {
+            // Price data changes frequently but can be cached briefly
+            price: 5000, // 5 seconds
+            // Balances should be fresh but can cache briefly
+            balance: 3000, // 3 seconds
+            // Contract data changes less frequently
+            contractData: 10000, // 10 seconds
+            // Supply data changes less frequently
+            supply: 10000, // 10 seconds
+            // NFT metadata rarely changes
+            metadata: 60000, // 60 seconds
+            // Tier/whitelist data changes infrequently
+            tier: 30000, // 30 seconds
+            // Default TTL
+            default: 5000 // 5 seconds
+        };
+        
+        // Methods that should never be cached
+        this.noCacheMethods = new Set([
+            'executeContractCall', // Transactions
+            'swapExactETHForTokens',
+            'swapExactTokensForETH',
+            'buy',
+            'sell',
+            'mint'
+        ]);
+        
+        // Setup event listeners for cache invalidation
+        this.setupEventListeners();
+        
+        // Debug mode
+        this.debug = false;
+    }
+
+    /**
+     * Setup event listeners for automatic cache invalidation
+     */
+    setupEventListeners() {
+        // Invalidate on transaction confirmation
+        this.eventBus.on('transaction:confirmed', () => {
+            this.invalidateByPattern('balance', 'price', 'contractData');
+            if (this.debug) {
+                console.log('[ContractCache] Invalidated cache due to transaction confirmation');
+            }
+        });
+
+        // Invalidate on account change
+        this.eventBus.on('account:changed', () => {
+            this.invalidateByPattern('balance');
+            if (this.debug) {
+                console.log('[ContractCache] Invalidated cache due to account change');
+            }
+        });
+
+        // Invalidate on network change
+        this.eventBus.on('network:changed', () => {
+            this.clear(); // Clear all cache on network change
+            if (this.debug) {
+                console.log('[ContractCache] Cleared cache due to network change');
+            }
+        });
+
+        // Invalidate on contract data update
+        this.eventBus.on('contractData:updated', () => {
+            this.invalidateByPattern('contractData', 'price', 'supply');
+            if (this.debug) {
+                console.log('[ContractCache] Invalidated cache due to contract data update');
+            }
+        });
+    }
+
+    /**
+     * Generate cache key from method name and arguments
+     * @param {string} method - Method name
+     * @param {Array} args - Method arguments
+     * @returns {string} - Cache key
+     */
+    generateKey(method, args = []) {
+        // Create a stable key from method and args
+        const argsKey = args.length > 0 
+            ? JSON.stringify(args.map(arg => {
+                // Handle BigNumber and other special types
+                if (arg && typeof arg === 'object' && arg.toString) {
+                    return arg.toString();
+                }
+                return arg;
+            }))
+            : '';
+        return `${method}:${argsKey}`;
+    }
+
+    /**
+     * Get cached value if available and not expired
+     * @param {string} method - Method name
+     * @param {Array} args - Method arguments
+     * @returns {any|null} - Cached value or null if not found/expired
+     */
+    get(method, args = []) {
+        // Don't cache certain methods
+        if (this.noCacheMethods.has(method)) {
+            return null;
+        }
+
+        const key = this.generateKey(method, args);
+        const entry = this.cache.get(key);
+
+        if (!entry) {
+            this.stats.misses++;
+            return null;
+        }
+
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            this.stats.misses++;
+            return null;
+        }
+
+        // Update access count
+        entry.accessCount++;
+        this.stats.hits++;
+        
+        if (this.debug) {
+            console.log(`[ContractCache] Cache HIT for ${method}`, args);
+        }
+
+        return entry.value;
+    }
+
+    /**
+     * Set cached value with TTL
+     * @param {string} method - Method name
+     * @param {Array} args - Method arguments
+     * @param {any} value - Value to cache
+     * @param {number} ttl - Time to live in milliseconds (optional, uses default if not provided)
+     */
+    set(method, args = [], value, ttl = null) {
+        // Don't cache certain methods
+        if (this.noCacheMethods.has(method)) {
+            return;
+        }
+
+        // Determine TTL based on method type
+        if (ttl === null) {
+            ttl = this.getTTLForMethod(method);
+        }
+
+        const key = this.generateKey(method, args);
+        const expiresAt = Date.now() + ttl;
+
+        this.cache.set(key, {
+            value,
+            expiresAt,
+            accessCount: 0,
+            method,
+            args,
+            cachedAt: Date.now()
+        });
+
+        this.stats.sets++;
+
+        if (this.debug) {
+            console.log(`[ContractCache] Cached ${method}`, args, `TTL: ${ttl}ms`);
+        }
+    }
+
+    /**
+     * Get TTL for a method based on its type
+     * @param {string} method - Method name
+     * @returns {number} - TTL in milliseconds
+     */
+    getTTLForMethod(method) {
+        const methodLower = method.toLowerCase();
+
+        // Price-related methods
+        if (methodLower.includes('price') || methodLower.includes('cost')) {
+            return this.defaultTTLs.price;
+        }
+
+        // Balance-related methods
+        if (methodLower.includes('balance')) {
+            return this.defaultTTLs.balance;
+        }
+
+        // Supply-related methods
+        if (methodLower.includes('supply') || methodLower.includes('total')) {
+            return this.defaultTTLs.supply;
+        }
+
+        // Metadata-related methods
+        if (methodLower.includes('metadata') || methodLower.includes('uri')) {
+            return this.defaultTTLs.metadata;
+        }
+
+        // Tier/whitelist-related methods
+        if (methodLower.includes('tier') || methodLower.includes('merkle') || methodLower.includes('proof')) {
+            return this.defaultTTLs.tier;
+        }
+
+        // Contract data methods
+        if (methodLower.includes('contract') || methodLower.includes('pool') || methodLower.includes('liquidity')) {
+            return this.defaultTTLs.contractData;
+        }
+
+        return this.defaultTTLs.default;
+    }
+
+    /**
+     * Invalidate cache entries matching patterns
+     * @param {...string} patterns - Patterns to match against method names
+     */
+    invalidateByPattern(...patterns) {
+        let invalidated = 0;
+
+        for (const [key, entry] of this.cache.entries()) {
+            const methodLower = entry.method.toLowerCase();
+            
+            if (patterns.some(pattern => methodLower.includes(pattern.toLowerCase()))) {
+                this.cache.delete(key);
+                invalidated++;
+            }
+        }
+
+        this.stats.invalidations += invalidated;
+
+        if (this.debug && invalidated > 0) {
+            console.log(`[ContractCache] Invalidated ${invalidated} entries matching patterns:`, patterns);
+        }
+    }
+
+    /**
+     * Invalidate specific cache entry
+     * @param {string} method - Method name
+     * @param {Array} args - Method arguments
+     */
+    invalidate(method, args = []) {
+        const key = this.generateKey(method, args);
+        if (this.cache.delete(key)) {
+            this.stats.invalidations++;
+            if (this.debug) {
+                console.log(`[ContractCache] Invalidated ${method}`, args);
+            }
+        }
+    }
+
+    /**
+     * Clear all cache
+     */
+    clear() {
+        const size = this.cache.size;
+        this.cache.clear();
+        this.stats.invalidations += size;
+        
+        if (this.debug) {
+            console.log('[ContractCache] Cleared all cache');
+        }
+    }
+
+    /**
+     * Get cache statistics
+     * @returns {Object} - Cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total > 0 ? (this.stats.hits / total * 100).toFixed(2) : 0;
+
+        return {
+            ...this.stats,
+            hitRate: `${hitRate}%`,
+            cacheSize: this.cache.size,
+            totalRequests: total
+        };
+    }
+
+    /**
+     * Warm cache by pre-fetching common data
+     * @param {Function} fetchFn - Function to fetch data
+     * @param {Array} methods - Methods to warm
+     */
+    async warmCache(fetchFn, methods = []) {
+        if (this.debug) {
+            console.log('[ContractCache] Warming cache for methods:', methods);
+        }
+
+        const promises = methods.map(async (method) => {
+            try {
+                const result = await fetchFn(method);
+                // Cache will be set by the wrapped method
+                return result;
+            } catch (error) {
+                console.warn(`[ContractCache] Failed to warm cache for ${method}:`, error);
+                return null;
+            }
+        });
+
+        await Promise.all(promises);
+    }
+
+    /**
+     * Enable or disable debug logging
+     * @param {boolean} enabled - Whether to enable debug mode
+     */
+    setDebug(enabled) {
+        this.debug = enabled;
+    }
+
+    /**
+     * Clean up expired entries (should be called periodically)
+     */
+    cleanup() {
+        const now = Date.now();
+        let cleaned = 0;
+
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+                cleaned++;
+            }
+        }
+
+        if (this.debug && cleaned > 0) {
+            console.log(`[ContractCache] Cleaned up ${cleaned} expired entries`);
+        }
+
+        return cleaned;
+    }
+}
+
+export default ContractCache;
+

package/src/services/IpfsService.js

@@ -0,0 +1,249 @@
+/**
+ * IPFS Service
+ * 
+ * Light client for IPFS resolution with gateway rotation and fallback.
+ * Handles both direct IPFS URIs and metadata fetching.
+ * 
+ * No secrets, no backend - pure client-side IPFS gateway resolution.
+ */
+
+/**
+ * Public IPFS gateways (in order of preference)
+ * These are public gateways that don't require authentication
+ */
+const IPFS_GATEWAYS = [
+    'https://w3s.link/ipfs/',
+    'https://cloudflare-ipfs.com/ipfs/',
+    'https://ipfs.io/ipfs/',
+    'https://gateway.pinata.cloud/ipfs/',
+    'https://dweb.link/ipfs/'
+];
+
+/**
+ * Get custom IPFS gateway from localStorage (user preference)
+ * @returns {string|null} Custom gateway base URL or null
+ */
+function getCustomGateway() {
+    try {
+        const custom = localStorage.getItem('customIpfsGatewayBaseUrl');
+        if (custom && typeof custom === 'string' && custom.trim()) {
+            const trimmed = custom.trim();
+            // Ensure it ends with /ipfs/ or just /
+            if (trimmed.endsWith('/ipfs/')) {
+                return trimmed;
+            } else if (trimmed.endsWith('/')) {
+                return trimmed + 'ipfs/';
+            } else {
+                return trimmed + '/ipfs/';
+            }
+        }
+    } catch (error) {
+        console.warn('[IpfsService] Failed to read custom gateway from localStorage:', error);
+    }
+    return null;
+}
+
+/**
+ * Get all available gateways (custom first, then public list)
+ * @returns {string[]} Array of gateway base URLs
+ */
+function getAllGateways() {
+    const custom = getCustomGateway();
+    return custom ? [custom, ...IPFS_GATEWAYS] : IPFS_GATEWAYS;
+}
+
+/**
+ * Check if a URI is an IPFS URI
+ * @param {string} uri - URI to check
+ * @returns {boolean} True if URI is IPFS
+ */
+export function isIpfsUri(uri) {
+    if (!uri || typeof uri !== 'string') {
+        return false;
+    }
+    return uri.toLowerCase().startsWith('ipfs://');
+}
+
+/**
+ * Normalize IPFS path by removing ipfs:// prefix
+ * Handles both ipfs://CID and ipfs://CID/path formats
+ * @param {string} ipfsUri - IPFS URI (e.g., ipfs://Qm... or ipfs://Qm.../path)
+ * @returns {string} Normalized path (e.g., Qm... or Qm.../path)
+ */
+export function normalizeIpfsPath(ipfsUri) {
+    if (!isIpfsUri(ipfsUri)) {
+        return ipfsUri;
+    }
+    
+    // Remove ipfs:// prefix
+    const path = ipfsUri.substring(7); // 'ipfs://' is 7 characters
+    
+    // Remove leading slash if present
+    return path.startsWith('/') ? path.substring(1) : path;
+}
+
+/**
+ * Resolve IPFS URI to HTTP URL using a specific gateway
+ * @param {string} ipfsUri - IPFS URI (e.g., ipfs://Qm...)
+ * @param {number} gatewayIndex - Index of gateway to use (0-based)
+ * @returns {string|null} HTTP URL or null if invalid
+ */
+export function resolveIpfsToHttp(ipfsUri, gatewayIndex = 0) {
+    if (!isIpfsUri(ipfsUri)) {
+        return ipfsUri; // Return as-is if not IPFS
+    }
+    
+    const gateways = getAllGateways();
+    if (gatewayIndex < 0 || gatewayIndex >= gateways.length) {
+        return null;
+    }
+    
+    const normalizedPath = normalizeIpfsPath(ipfsUri);
+    const gateway = gateways[gatewayIndex];
+    
+    return gateway + normalizedPath;
+}
+
+/**
+ * Fetch JSON from IPFS or HTTP URL with gateway rotation
+ * @param {string} urlOrIpfs - HTTP URL or IPFS URI
+ * @param {object} options - Fetch options (timeout, etc.)
+ * @returns {Promise<object>} Parsed JSON data
+ * @throws {Error} If all gateways fail or JSON is invalid
+ */
+export async function fetchJsonWithIpfsSupport(urlOrIpfs, options = {}) {
+    const { timeout = 10000, ...fetchOptions } = options;
+    
+    // If it's not an IPFS URI, use regular fetch
+    if (!isIpfsUri(urlOrIpfs)) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        
+        try {
+            const response = await fetch(urlOrIpfs, {
+                ...fetchOptions,
+                signal: controller.signal
+            });
+            
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            
+            const json = await response.json();
+            clearTimeout(timeoutId);
+            return json;
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') {
+                throw new Error(`Request timeout after ${timeout}ms`);
+            }
+            throw error;
+        }
+    }
+    
+    // IPFS URI - try gateways in order
+    const gateways = getAllGateways();
+    const normalizedPath = normalizeIpfsPath(urlOrIpfs);
+    const errors = [];
+    
+    for (let i = 0; i < gateways.length; i++) {
+        const gateway = gateways[i];
+        const httpUrl = gateway + normalizedPath;
+        
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        
+        try {
+            const response = await fetch(httpUrl, {
+                ...fetchOptions,
+                signal: controller.signal
+            });
+            
+            clearTimeout(timeoutId);
+            
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            
+            const json = await response.json();
+            
+            // Success - log which gateway worked (for debugging)
+            if (i > 0) {
+                console.log(`[IpfsService] Resolved IPFS via gateway ${i + 1}/${gateways.length}: ${gateway}`);
+            }
+            
+            return json;
+        } catch (error) {
+            clearTimeout(timeoutId);
+            
+            const errorMsg = error.name === 'AbortError' 
+                ? `Timeout after ${timeout}ms`
+                : error.message || 'Unknown error';
+            
+            errors.push(`Gateway ${i + 1} (${gateway}): ${errorMsg}`);
+            
+            // Continue to next gateway
+            continue;
+        }
+    }
+    
+    // All gateways failed
+    throw new Error(
+        `Failed to fetch IPFS content after trying ${gateways.length} gateways:\n` +
+        errors.join('\n')
+    );
+}
+
+/**
+ * Test if an image URL can be loaded (for gateway rotation)
+ * @param {string} url - HTTP URL to test
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<boolean>} True if image loads successfully
+ */
+export function testImageLoad(url, timeout = 5000) {
+    return new Promise((resolve) => {
+        const img = new Image();
+        const timeoutId = setTimeout(() => {
+            img.onload = null;
+            img.onerror = null;
+            resolve(false);
+        }, timeout);
+        
+        img.onload = () => {
+            clearTimeout(timeoutId);
+            resolve(true);
+        };
+        
+        img.onerror = () => {
+            clearTimeout(timeoutId);
+            resolve(false);
+        };
+        
+        img.src = url;
+    });
+}
+
+/**
+ * Get all available gateways (for UI display or debugging)
+ * @returns {string[]} Array of gateway base URLs
+ */
+export function getAvailableGateways() {
+    return getAllGateways();
+}
+
+/**
+ * Set custom IPFS gateway (user preference)
+ * @param {string} gatewayBaseUrl - Base URL of custom gateway (e.g., 'https://mygateway.com/ipfs/')
+ */
+export function setCustomGateway(gatewayBaseUrl) {
+    try {
+        if (gatewayBaseUrl) {
+            localStorage.setItem('customIpfsGatewayBaseUrl', gatewayBaseUrl);
+        } else {
+            localStorage.removeItem('customIpfsGatewayBaseUrl');
+        }
+    } catch (error) {
+        console.warn('[IpfsService] Failed to save custom gateway to localStorage:', error);
+    }
+}
+