@sschepis/magazine 0.1.0

package/src/components/NetworkManager.js

@@ -0,0 +1,461 @@
+import * as ethers from 'ethers';
+import Logger from './Logger.js';
+
+/**
+ * LRUCache - Simple Least Recently Used cache using Map ordering
+ */
+class LRUCache {
+    constructor(maxSize = 500) { this.maxSize = maxSize; this.cache = new Map(); }
+    get(key) { if (!this.cache.has(key)) return undefined; const v = this.cache.get(key); this.cache.delete(key); this.cache.set(key, v); return v; }
+    set(key, value) { if (this.cache.has(key)) this.cache.delete(key); else if (this.cache.size >= this.maxSize) this.cache.delete(this.cache.keys().next().value); this.cache.set(key, value); }
+    clear() { this.cache.clear(); }
+    get size() { return this.cache.size; }
+}
+
+/**
+ * RateLimiter - Token-bucket rate limiter for throttling RPC calls
+ */
+class RateLimiter {
+    constructor(maxPerSecond = 25) {
+        this.maxPerSecond = maxPerSecond;
+        this.tokens = maxPerSecond;
+        this.lastRefill = Date.now();
+        this.queue = [];
+    }
+    async acquire() {
+        this._refill();
+        if (this.tokens > 0) { this.tokens--; return; }
+        return new Promise(resolve => this.queue.push(resolve));
+    }
+    _refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000;
+        this.tokens = Math.min(this.maxPerSecond, this.tokens + elapsed * this.maxPerSecond);
+        this.lastRefill = now;
+        while (this.queue.length > 0 && this.tokens > 0) { this.tokens--; this.queue.shift()(); }
+    }
+}
+
+/**
+ * NetworkManager - Handles provider and network management
+ *
+ * Supports multi-provider failover, LRU caching for blocks/timestamps,
+ * and token-bucket rate limiting for RPC calls.
+ */
+export default class NetworkManager {
+    constructor(config, retryOperation) {
+        this.config = config;
+        this.retryOperation = retryOperation;
+        this.logger = new Logger({
+            context: 'NetworkManager',
+            level: config?.logLevel || 'info'
+        });
+
+        this.logger.debug('Initializing NetworkManager', {
+            provider: config.provider,
+            networkId: config.networkId
+        });
+
+        // Multi-provider failover setup
+        this.providers = [];
+        this.currentProviderIndex = 0;
+        this._initializeProviders(config.provider);
+
+        // Set the active provider to the first one
+        this.provider = this.providers[0];
+
+        this.interface = new ethers.Interface(config.abi);
+
+        // Initialize LRU caches for blocks and timestamps
+        const cacheSize = config.cacheSize || 500;
+        this.blockCache = new LRUCache(cacheSize);
+        this.timestampCache = new LRUCache(cacheSize);
+        this.logger.debug('LRU caches initialized', { cacheSize });
+
+        // Initialize rate limiter
+        const rateLimit = config.rateLimit || 25;
+        this.rateLimiter = new RateLimiter(rateLimit);
+        this.logger.debug('Rate limiter initialized', { maxPerSecond: rateLimit });
+
+        // Initialize event mappings
+        this.events = {};
+        this.eventsByTopic = {}; // Map topic hash to event name
+
+        this._initializeEvents();
+
+        this.logger.info('NetworkManager initialized successfully', {
+            eventCount: Object.keys(this.eventsByTopic).length,
+            contractAddress: config.address,
+            providerCount: this.providers.length
+        });
+    }
+
+    /**
+     * Initialize providers from config. Accepts a single provider (string or
+     * ethers provider object) or an array of providers.
+     */
+    _initializeProviders(providerConfig) {
+        const providerList = Array.isArray(providerConfig) ? providerConfig : [providerConfig];
+
+        for (const entry of providerList) {
+            if (typeof entry === 'string') {
+                const provider = new ethers.JsonRpcProvider(entry);
+                this.providers.push(provider);
+                this.logger.debug('Created JsonRpcProvider from URL', { url: entry });
+            } else if (entry && typeof entry.getNetwork === 'function') {
+                this.providers.push(entry);
+                this.logger.debug('Using provided ethers provider object', {
+                    providerType: entry.constructor.name
+                });
+            } else {
+                throw new Error('Each provider must be either a string URL or an ethers provider object');
+            }
+        }
+
+        if (this.providers.length === 0) {
+            throw new Error('At least one provider must be specified');
+        }
+
+        this.logger.debug('Providers initialized', { count: this.providers.length });
+    }
+
+    /**
+     * Switch to the next provider in the list on failure.
+     * Returns true if a new provider was activated, false if all have been tried.
+     */
+    _switchProvider(error) {
+        const previousIndex = this.currentProviderIndex;
+        this.currentProviderIndex = (this.currentProviderIndex + 1) % this.providers.length;
+
+        // If we've cycled back to the starting provider, all have been tried
+        if (this.currentProviderIndex === previousIndex && this.providers.length === 1) {
+            this.logger.error('Single provider failed, no failover available', {
+                error: error.message
+            });
+            return false;
+        }
+
+        this.provider = this.providers[this.currentProviderIndex];
+        this.logger.warn('Switching provider due to failure', {
+            error: error.message,
+            previousIndex,
+            newIndex: this.currentProviderIndex,
+            totalProviders: this.providers.length
+        });
+
+        return true;
+    }
+
+    /**
+     * Execute a function through the rate limiter.
+     * Acquires a token before executing the call.
+     */
+    async _throttledCall(fn) {
+        await this.rateLimiter.acquire();
+        return fn();
+    }
+
+    /**
+     * Execute a provider call with failover support.
+     * Tries each provider in sequence before giving up.
+     */
+    async _callWithFailover(fn, description) {
+        const startIndex = this.currentProviderIndex;
+        let lastError;
+        let attempts = 0;
+
+        do {
+            try {
+                return await this._throttledCall(() => fn(this.provider));
+            } catch (error) {
+                lastError = error;
+                attempts++;
+                this.logger.warn('Provider call failed', {
+                    description,
+                    providerIndex: this.currentProviderIndex,
+                    attempt: attempts,
+                    error: error.message
+                });
+
+                if (this.providers.length > 1) {
+                    this._switchProvider(error);
+                    // If we've rotated back to the start, stop
+                    if (this.currentProviderIndex === startIndex) {
+                        break;
+                    }
+                } else {
+                    break;
+                }
+            }
+        } while (true);
+
+        throw lastError;
+    }
+
+    // Initialize event mappings from ABI
+    _initializeEvents() {
+        let eventCount = 0;
+
+        for (const fragment of this.config.abi) {
+            if (fragment.type === 'event') {
+                const eventName = fragment.name;
+                this.events[eventName] = new ethers.Interface([fragment]);
+
+                // Create mapping from topic hash to event name
+                try {
+                    const eventFragment = this.interface.getEvent(eventName);
+                    const topicHash = eventFragment.topicHash;
+                    this.eventsByTopic[topicHash] = eventName;
+                    eventCount++;
+
+                    this.logger.debug('Event mapping created', {
+                        eventName,
+                        topicHash
+                    });
+                } catch (error) {
+                    this.logger.warn('Failed to get topic hash for event', {
+                        eventName,
+                        error: error.message
+                    });
+                }
+            }
+        }
+
+        this.logger.debug('Event initialization completed', { eventCount });
+    }
+
+    // Get the latest block number from the network
+    async getLatestBlockNumber() {
+        return this.logger.time('getLatestBlockNumber', async () => {
+            const blockNumber = await this.retryOperation(
+                () => this._callWithFailover(
+                    (provider) => provider.getBlockNumber(),
+                    'getLatestBlockNumber'
+                ),
+                'Getting latest block number'
+            );
+
+            this.logger.logNetworkActivity('getLatestBlockNumber', { blockNumber });
+            return blockNumber;
+        });
+    }
+
+    // Get logs from the blockchain within a block range
+    async getLogs(fromBlock, toBlock) {
+        return this.logger.time('getLogs', async () => {
+            this.logger.logNetworkActivity('getLogs_request', { fromBlock, toBlock, address: this.config.address });
+
+            const logs = await this.retryOperation(
+                () => this._callWithFailover(
+                    (provider) => provider.getLogs({
+                        address: this.config.address,
+                        fromBlock,
+                        toBlock
+                    }),
+                    'getLogs'
+                ),
+                `Getting logs for blocks ${fromBlock}-${toBlock}`
+            );
+
+            this.logger.logNetworkActivity('getLogs_response', {
+                fromBlock,
+                toBlock,
+                logCount: logs.length
+            });
+
+            return logs;
+        });
+    }
+
+    // Parse a raw log into structured event data
+    parseLog(log) {
+        const topicHash = log.topics[0];
+        const eventName = this.eventsByTopic[topicHash];
+
+        if (!eventName) {
+            this.logger.trace('Unknown event topic', { topicHash, availableTopics: Object.keys(this.eventsByTopic) });
+            return null;
+        }
+
+        try {
+            const parsedLog = this.interface.parseLog(log);
+            const result = {
+                eventName,
+                parsedLog,
+                eventData: {
+                    ...parsedLog.args,
+                    blockNumber: log.blockNumber,
+                    transactionHash: log.transactionHash,
+                    logIndex: log.logIndex,
+                    timestamp: Date.now()
+                }
+            };
+
+            this.logger.debug('Successfully parsed log', {
+                eventName,
+                blockNumber: log.blockNumber,
+                transactionHash: log.transactionHash,
+                logIndex: log.logIndex
+            });
+
+            return result;
+        } catch (error) {
+            this.logger.warn('Failed to parse log for event', {
+                eventName,
+                blockNumber: log.blockNumber,
+                transactionHash: log.transactionHash,
+                error: error.message
+            });
+            return null;
+        }
+    }
+
+    // Create unique event key for deduplication
+    createEventKey(log) {
+        return `${log.transactionHash}-${log.logIndex}`;
+    }
+
+    // Get network information
+    async getNetworkInfo() {
+        return this.retryOperation(async () => {
+            const network = await this._callWithFailover(
+                (provider) => provider.getNetwork(),
+                'getNetwork'
+            );
+            const blockNumber = await this._callWithFailover(
+                (provider) => provider.getBlockNumber(),
+                'getBlockNumber'
+            );
+
+            return {
+                chainId: Number(network.chainId),
+                name: network.name,
+                currentBlock: blockNumber,
+                expectedNetworkId: this.config.networkId
+            };
+        }, 'Getting network information');
+    }
+
+    // Validate network connection and configuration
+    async validateNetwork() {
+        const networkInfo = await this.getNetworkInfo();
+
+        if (networkInfo.chainId !== this.config.networkId) {
+            throw new Error(
+                `Network mismatch: expected ${this.config.networkId}, got ${networkInfo.chainId}`
+            );
+        }
+
+        return networkInfo;
+    }
+
+    // Get contract code to verify contract exists
+    async validateContract() {
+        return this.retryOperation(async () => {
+            const code = await this._callWithFailover(
+                (provider) => provider.getCode(this.config.address),
+                'getCode'
+            );
+            if (code === '0x') {
+                throw new Error(`No contract found at address ${this.config.address}`);
+            }
+            return true;
+        }, 'Validating contract');
+    }
+
+    // Get a block by number, with LRU caching
+    async getBlock(blockNumber) {
+        const cached = this.blockCache.get(blockNumber);
+        if (cached !== undefined) {
+            this.logger.debug('Block cache hit', { blockNumber });
+            return cached;
+        }
+
+        const block = await this.retryOperation(async () => {
+            return this._callWithFailover(
+                (provider) => provider.getBlock(blockNumber),
+                `getBlock(${blockNumber})`
+            );
+        }, `Getting block ${blockNumber}`);
+
+        if (block) {
+            this.blockCache.set(blockNumber, block);
+        }
+
+        return block;
+    }
+
+    // Get block timestamp, with LRU caching
+    async getBlockTimestamp(blockNumber) {
+        const cached = this.timestampCache.get(blockNumber);
+        if (cached !== undefined) {
+            this.logger.debug('Timestamp cache hit', { blockNumber });
+            return cached;
+        }
+
+        const block = await this.getBlock(blockNumber);
+        const timestamp = block ? block.timestamp : null;
+
+        if (timestamp !== null) {
+            this.timestampCache.set(blockNumber, timestamp);
+        }
+
+        return timestamp;
+    }
+
+    // Get transaction receipt
+    async getTransactionReceipt(txHash) {
+        return this.retryOperation(
+            () => this._callWithFailover(
+                (provider) => provider.getTransactionReceipt(txHash),
+                'getTransactionReceipt'
+            ),
+            `Getting transaction receipt for ${txHash}`
+        );
+    }
+
+    // Get gas price information
+    async getGasPrice() {
+        return this.retryOperation(
+            () => this._callWithFailover(
+                (provider) => provider.getFeeData(),
+                'getFeeData'
+            ),
+            'Getting gas price information'
+        );
+    }
+
+    // Get provider instance for advanced operations
+    getProvider() {
+        return this.provider;
+    }
+
+    // Get ethers interface for manual parsing
+    getInterface() {
+        return this.interface;
+    }
+
+    // Get event mappings
+    getEventMappings() {
+        return {
+            events: { ...this.events },
+            eventsByTopic: { ...this.eventsByTopic }
+        };
+    }
+
+    // Clear all caches
+    clearCaches() {
+        this.blockCache.clear();
+        this.timestampCache.clear();
+        this.logger.debug('All caches cleared');
+    }
+
+    // Get cache statistics
+    getCacheStats() {
+        return {
+            blockCacheSize: this.blockCache.size,
+            timestampCacheSize: this.timestampCache.size,
+            maxCacheSize: this.blockCache.maxSize
+        };
+    }
+}