@monygroupcorp/micro-web3 0.1.1 → 1.2.0

package/docs/plans/2026-01-22-event-indexer.md

@@ -0,0 +1,3642 @@
+# EventIndexer Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add client-side event indexing to micro-web3 with three abstraction levels (Events, Entities, Patterns), persistent storage, and reactive component integration.
+
+**Architecture:** EventIndexer is the main service coordinating four internal modules: StorageAdapter (IndexedDB/Memory), SyncEngine (historical + real-time), QueryEngine (filtering/pagination), and EntityResolver (domain objects from events). Components integrate via `useIndexer` hook with automatic subscription management.
+
+**Tech Stack:** ethers.js ^5.7.2 (existing), IndexedDB (native), microact Component (peer dependency)
+
+---
+
+## Implementation Order
+
+1. Storage Layer (foundation)
+2. Query Engine (depends on storage)
+3. Sync Engine (depends on storage)
+4. Entity Resolver (depends on query engine)
+5. Patterns API (depends on entity resolver)
+6. EventIndexer Service (orchestrates all)
+7. Component Integration (useIndexer hook)
+8. UI Components (SyncProgressBar)
+9. **Settings Modal & User Storage Controls** (NEW)
+10. Existing Service Modifications
+11. Export Updates & Version Bump
+12. Tests (last, as requested)
+
+---
+
+## Task 1: Storage Adapter Interface
+
+**Files:**
+- Create: `src/storage/StorageAdapter.js`
+
+**Step 1: Create the storage adapter base class**
+
+```javascript
+// src/storage/StorageAdapter.js
+
+/**
+ * Abstract storage adapter interface for EventIndexer.
+ * Implementations must handle all async operations.
+ */
+class StorageAdapter {
+  /**
+   * Initialize storage with configuration.
+   * @param {Object} config - Storage configuration
+   * @param {string} config.dbName - Database name
+   * @param {number} config.version - Schema version
+   * @param {Object[]} config.eventTypes - Event types from ABI with indexed params
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('StorageAdapter.initialize() must be implemented');
+  }
+
+  /**
+   * Store multiple events atomically.
+   * @param {IndexedEvent[]} events - Events to store
+   * @returns {Promise<void>}
+   */
+  async putEvents(events) {
+    throw new Error('StorageAdapter.putEvents() must be implemented');
+  }
+
+  /**
+   * Get single event by type and ID.
+   * @param {string} type - Event type name
+   * @param {string} id - Event ID (txHash-logIndex)
+   * @returns {Promise<IndexedEvent|null>}
+   */
+  async getEvent(type, id) {
+    throw new Error('StorageAdapter.getEvent() must be implemented');
+  }
+
+  /**
+   * Query events with filters, sorting, pagination.
+   * @param {string} type - Event type name
+   * @param {QueryOptions} options - Query options
+   * @returns {Promise<QueryResult>}
+   */
+  async queryEvents(type, options) {
+    throw new Error('StorageAdapter.queryEvents() must be implemented');
+  }
+
+  /**
+   * Count events matching filter.
+   * @param {string} type - Event type name
+   * @param {Object} where - Filter conditions
+   * @returns {Promise<number>}
+   */
+  async countEvents(type, where) {
+    throw new Error('StorageAdapter.countEvents() must be implemented');
+  }
+
+  /**
+   * Delete events by IDs.
+   * @param {string} type - Event type name
+   * @param {string[]} ids - Event IDs to delete
+   * @returns {Promise<void>}
+   */
+  async deleteEvents(type, ids) {
+    throw new Error('StorageAdapter.deleteEvents() must be implemented');
+  }
+
+  /**
+   * Delete all events after a block number (for reorg recovery).
+   * @param {number} blockNumber - Delete events after this block
+   * @returns {Promise<void>}
+   */
+  async deleteEventsAfterBlock(blockNumber) {
+    throw new Error('StorageAdapter.deleteEventsAfterBlock() must be implemented');
+  }
+
+  /**
+   * Get sync state.
+   * @returns {Promise<SyncState|null>}
+   */
+  async getSyncState() {
+    throw new Error('StorageAdapter.getSyncState() must be implemented');
+  }
+
+  /**
+   * Update sync state.
+   * @param {SyncState} state - New sync state
+   * @returns {Promise<void>}
+   */
+  async setSyncState(state) {
+    throw new Error('StorageAdapter.setSyncState() must be implemented');
+  }
+
+  /**
+   * Get schema version.
+   * @returns {Promise<number>}
+   */
+  async getVersion() {
+    throw new Error('StorageAdapter.getVersion() must be implemented');
+  }
+
+  /**
+   * Set schema version.
+   * @param {number} version - New version
+   * @returns {Promise<void>}
+   */
+  async setVersion(version) {
+    throw new Error('StorageAdapter.setVersion() must be implemented');
+  }
+
+  /**
+   * Clear all data.
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    throw new Error('StorageAdapter.clear() must be implemented');
+  }
+
+  /**
+   * Close connection and cleanup.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    throw new Error('StorageAdapter.close() must be implemented');
+  }
+}
+
+export default StorageAdapter;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/storage/StorageAdapter.js
+git commit -m "feat(storage): add StorageAdapter base class interface"
+```
+
+---
+
+## Task 2: Memory Storage Adapter
+
+**Files:**
+- Create: `src/storage/MemoryAdapter.js`
+
+**Step 1: Implement MemoryAdapter**
+
+```javascript
+// src/storage/MemoryAdapter.js
+
+import StorageAdapter from './StorageAdapter.js';
+
+/**
+ * In-memory storage adapter for EventIndexer.
+ * Used as fallback when IndexedDB unavailable (SSR, private browsing).
+ * No persistence across sessions.
+ */
+class MemoryAdapter extends StorageAdapter {
+  constructor() {
+    super();
+    this.stores = new Map(); // eventType -> Map<id, event>
+    this.syncState = null;
+    this.version = 0;
+    this.config = null;
+  }
+
+  async initialize(config) {
+    this.config = config;
+
+    // Create store for each event type
+    for (const eventType of config.eventTypes) {
+      this.stores.set(eventType.name, new Map());
+    }
+
+    // Check version for migration
+    if (config.version > this.version) {
+      await this.clear();
+      this.version = config.version;
+    }
+  }
+
+  async putEvents(events) {
+    for (const event of events) {
+      const store = this.stores.get(event.type);
+      if (!store) {
+        // Lazily create store for unknown event types
+        this.stores.set(event.type, new Map());
+      }
+      this.stores.get(event.type).set(event.id, event);
+    }
+  }
+
+  async getEvent(type, id) {
+    const store = this.stores.get(type);
+    if (!store) return null;
+    return store.get(id) || null;
+  }
+
+  async queryEvents(type, options = {}) {
+    const store = this.stores.get(type);
+    if (!store) {
+      return { events: [], total: 0, hasMore: false };
+    }
+
+    let events = Array.from(store.values());
+
+    // Apply where filters
+    if (options.where) {
+      events = events.filter(event => this._matchesWhere(event, options.where));
+    }
+
+    const total = events.length;
+
+    // Sort
+    const orderBy = options.orderBy || 'blockNumber';
+    const order = options.order || 'desc';
+    events.sort((a, b) => {
+      const aVal = this._getNestedValue(a, orderBy);
+      const bVal = this._getNestedValue(b, orderBy);
+      if (aVal < bVal) return order === 'asc' ? -1 : 1;
+      if (aVal > bVal) return order === 'asc' ? 1 : -1;
+      return 0;
+    });
+
+    // Pagination
+    const offset = options.offset || 0;
+    const limit = options.limit || 100;
+    const paged = events.slice(offset, offset + limit);
+
+    return {
+      events: paged,
+      total,
+      hasMore: offset + limit < total
+    };
+  }
+
+  async countEvents(type, where) {
+    const store = this.stores.get(type);
+    if (!store) return 0;
+
+    if (!where) return store.size;
+
+    let count = 0;
+    for (const event of store.values()) {
+      if (this._matchesWhere(event, where)) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  async deleteEvents(type, ids) {
+    const store = this.stores.get(type);
+    if (!store) return;
+
+    for (const id of ids) {
+      store.delete(id);
+    }
+  }
+
+  async deleteEventsAfterBlock(blockNumber) {
+    for (const store of this.stores.values()) {
+      for (const [id, event] of store.entries()) {
+        if (event.blockNumber > blockNumber) {
+          store.delete(id);
+        }
+      }
+    }
+  }
+
+  async getSyncState() {
+    return this.syncState;
+  }
+
+  async setSyncState(state) {
+    this.syncState = { ...state };
+  }
+
+  async getVersion() {
+    return this.version;
+  }
+
+  async setVersion(version) {
+    this.version = version;
+  }
+
+  async clear() {
+    for (const store of this.stores.values()) {
+      store.clear();
+    }
+    this.syncState = null;
+  }
+
+  async close() {
+    // No-op for memory adapter
+  }
+
+  // Helper: check if event matches where clause
+  _matchesWhere(event, where) {
+    for (const [key, value] of Object.entries(where)) {
+      const eventValue = this._getNestedValue(event, key);
+
+      // Handle array values (OR condition)
+      if (Array.isArray(value)) {
+        if (!value.includes(eventValue)) return false;
+      }
+      // Handle comparison operators
+      else if (typeof value === 'object' && value !== null) {
+        if (value.$gt !== undefined && !(eventValue > value.$gt)) return false;
+        if (value.$gte !== undefined && !(eventValue >= value.$gte)) return false;
+        if (value.$lt !== undefined && !(eventValue < value.$lt)) return false;
+        if (value.$lte !== undefined && !(eventValue <= value.$lte)) return false;
+        if (value.$ne !== undefined && eventValue === value.$ne) return false;
+      }
+      // Direct equality (case-insensitive for addresses)
+      else {
+        const normalizedEvent = typeof eventValue === 'string' ? eventValue.toLowerCase() : eventValue;
+        const normalizedValue = typeof value === 'string' ? value.toLowerCase() : value;
+        if (normalizedEvent !== normalizedValue) return false;
+      }
+    }
+    return true;
+  }
+
+  // Helper: get nested value from object using dot notation
+  _getNestedValue(obj, path) {
+    // Check indexed params first, then data, then direct
+    if (path.startsWith('indexed.')) {
+      return obj.indexed?.[path.slice(8)];
+    }
+    if (path.startsWith('data.')) {
+      return obj.data?.[path.slice(5)];
+    }
+
+    // Try indexed, then data, then direct property
+    if (obj.indexed?.[path] !== undefined) return obj.indexed[path];
+    if (obj.data?.[path] !== undefined) return obj.data[path];
+    return obj[path];
+  }
+}
+
+export default MemoryAdapter;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/storage/MemoryAdapter.js
+git commit -m "feat(storage): add MemoryAdapter for in-memory event storage"
+```
+
+---
+
+## Task 3: IndexedDB Storage Adapter
+
+**Files:**
+- Create: `src/storage/IndexedDBAdapter.js`
+
+**Step 1: Implement IndexedDBAdapter**
+
+```javascript
+// src/storage/IndexedDBAdapter.js
+
+import StorageAdapter from './StorageAdapter.js';
+
+/**
+ * IndexedDB storage adapter for EventIndexer.
+ * Provides persistent event storage with auto-generated indexes.
+ */
+class IndexedDBAdapter extends StorageAdapter {
+  constructor() {
+    super();
+    this.db = null;
+    this.config = null;
+    this.dbName = null;
+  }
+
+  async initialize(config) {
+    this.config = config;
+    this.dbName = config.dbName;
+
+    // Check for existing version
+    const existingVersion = await this._getStoredVersion();
+
+    // Handle migration: if config version is higher, we need to clear and rebuild
+    const needsMigration = existingVersion !== null && config.version > existingVersion;
+
+    if (needsMigration) {
+      console.log(`[IndexedDBAdapter] Migrating from v${existingVersion} to v${config.version}`);
+      await this._deleteDatabase();
+    }
+
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, config.version);
+
+      request.onerror = () => {
+        reject(new Error(`Failed to open IndexedDB: ${request.error?.message}`));
+      };
+
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve();
+      };
+
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        this._createStores(db, config.eventTypes);
+      };
+    });
+  }
+
+  _createStores(db, eventTypes) {
+    // Create store for each event type
+    for (const eventType of eventTypes) {
+      const storeName = `events_${eventType.name}`;
+
+      if (!db.objectStoreNames.contains(storeName)) {
+        const store = db.createObjectStore(storeName, { keyPath: 'id' });
+
+        // Create indexes for indexed params (from ABI)
+        for (const param of eventType.indexedParams || []) {
+          store.createIndex(`param_${param}`, `indexed.${param}`, { unique: false });
+        }
+
+        // Always create blockNumber and timestamp indexes
+        store.createIndex('blockNumber', 'blockNumber', { unique: false });
+        store.createIndex('timestamp', 'timestamp', { unique: false });
+      }
+    }
+
+    // Create sync state store
+    if (!db.objectStoreNames.contains('syncState')) {
+      db.createObjectStore('syncState', { keyPath: 'id' });
+    }
+
+    // Create meta store for version tracking
+    if (!db.objectStoreNames.contains('meta')) {
+      db.createObjectStore('meta', { keyPath: 'key' });
+    }
+  }
+
+  async _getStoredVersion() {
+    return new Promise((resolve) => {
+      const request = indexedDB.open(this.dbName);
+      request.onsuccess = () => {
+        const db = request.result;
+        const version = db.version;
+        db.close();
+        resolve(version);
+      };
+      request.onerror = () => resolve(null);
+    });
+  }
+
+  async _deleteDatabase() {
+    return new Promise((resolve, reject) => {
+      if (this.db) {
+        this.db.close();
+        this.db = null;
+      }
+      const request = indexedDB.deleteDatabase(this.dbName);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async putEvents(events) {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+    if (events.length === 0) return;
+
+    // Group events by type for batch operations
+    const eventsByType = new Map();
+    for (const event of events) {
+      if (!eventsByType.has(event.type)) {
+        eventsByType.set(event.type, []);
+      }
+      eventsByType.get(event.type).push(event);
+    }
+
+    // Write each type in a transaction
+    const promises = [];
+    for (const [type, typeEvents] of eventsByType) {
+      promises.push(this._putEventsOfType(type, typeEvents));
+    }
+    await Promise.all(promises);
+  }
+
+  async _putEventsOfType(type, events) {
+    const storeName = `events_${type}`;
+
+    // Check if store exists, create if needed
+    if (!this.db.objectStoreNames.contains(storeName)) {
+      // Need to reopen with version upgrade to add new store
+      await this._addStore(type);
+    }
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, 'readwrite');
+      const store = tx.objectStore(storeName);
+
+      for (const event of events) {
+        store.put(event);
+      }
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async _addStore(eventType) {
+    // Close current connection
+    const currentVersion = this.db.version;
+    this.db.close();
+
+    // Reopen with incremented version
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, currentVersion + 1);
+
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        const storeName = `events_${eventType}`;
+        if (!db.objectStoreNames.contains(storeName)) {
+          db.createObjectStore(storeName, { keyPath: 'id' });
+        }
+      };
+
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve();
+      };
+
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async getEvent(type, id) {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+
+    const storeName = `events_${type}`;
+    if (!this.db.objectStoreNames.contains(storeName)) {
+      return null;
+    }
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, 'readonly');
+      const store = tx.objectStore(storeName);
+      const request = store.get(id);
+
+      request.onsuccess = () => resolve(request.result || null);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async queryEvents(type, options = {}) {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+
+    const storeName = `events_${type}`;
+    if (!this.db.objectStoreNames.contains(storeName)) {
+      return { events: [], total: 0, hasMore: false };
+    }
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, 'readonly');
+      const store = tx.objectStore(storeName);
+
+      // Get all events (we'll filter/sort in memory for complex queries)
+      // For simple indexed queries, we could use IDB indexes, but this is more flexible
+      const request = store.getAll();
+
+      request.onsuccess = () => {
+        let events = request.result;
+
+        // Apply where filters
+        if (options.where) {
+          events = events.filter(event => this._matchesWhere(event, options.where));
+        }
+
+        const total = events.length;
+
+        // Sort
+        const orderBy = options.orderBy || 'blockNumber';
+        const order = options.order || 'desc';
+        events.sort((a, b) => {
+          const aVal = this._getNestedValue(a, orderBy);
+          const bVal = this._getNestedValue(b, orderBy);
+          if (aVal < bVal) return order === 'asc' ? -1 : 1;
+          if (aVal > bVal) return order === 'asc' ? 1 : -1;
+          return 0;
+        });
+
+        // Pagination
+        const offset = options.offset || 0;
+        const limit = options.limit || 100;
+        const paged = events.slice(offset, offset + limit);
+
+        resolve({
+          events: paged,
+          total,
+          hasMore: offset + limit < total
+        });
+      };
+
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async countEvents(type, where) {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+
+    const storeName = `events_${type}`;
+    if (!this.db.objectStoreNames.contains(storeName)) {
+      return 0;
+    }
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, 'readonly');
+      const store = tx.objectStore(storeName);
+
+      if (!where) {
+        const request = store.count();
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+      } else {
+        // Need to filter manually
+        const request = store.getAll();
+        request.onsuccess = () => {
+          const count = request.result.filter(e => this._matchesWhere(e, where)).length;
+          resolve(count);
+        };
+        request.onerror = () => reject(request.error);
+      }
+    });
+  }
+
+  async deleteEvents(type, ids) {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+
+    const storeName = `events_${type}`;
+    if (!this.db.objectStoreNames.contains(storeName)) return;
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, 'readwrite');
+      const store = tx.objectStore(storeName);
+
+      for (const id of ids) {
+        store.delete(id);
+      }
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async deleteEventsAfterBlock(blockNumber) {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+
+    const storeNames = Array.from(this.db.objectStoreNames)
+      .filter(name => name.startsWith('events_'));
+
+    for (const storeName of storeNames) {
+      await this._deleteEventsAfterBlockInStore(storeName, blockNumber);
+    }
+  }
+
+  async _deleteEventsAfterBlockInStore(storeName, blockNumber) {
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, 'readwrite');
+      const store = tx.objectStore(storeName);
+      const index = store.index('blockNumber');
+      const range = IDBKeyRange.lowerBound(blockNumber, true); // exclusive
+
+      const request = index.openCursor(range);
+      request.onsuccess = (event) => {
+        const cursor = event.target.result;
+        if (cursor) {
+          cursor.delete();
+          cursor.continue();
+        }
+      };
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async getSyncState() {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction('syncState', 'readonly');
+      const store = tx.objectStore('syncState');
+      const request = store.get('current');
+
+      request.onsuccess = () => resolve(request.result || null);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async setSyncState(state) {
+    if (!this.db) throw new Error('IndexedDBAdapter not initialized');
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction('syncState', 'readwrite');
+      const store = tx.objectStore('syncState');
+      const request = store.put({ id: 'current', ...state });
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async getVersion() {
+    if (!this.db) return 0;
+    return this.db.version;
+  }
+
+  async setVersion(version) {
+    // Version is managed by IndexedDB upgrade mechanism
+    // This is a no-op, included for interface compliance
+  }
+
+  async clear() {
+    if (!this.db) return;
+
+    const storeNames = Array.from(this.db.objectStoreNames);
+
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeNames, 'readwrite');
+
+      for (const storeName of storeNames) {
+        tx.objectStore(storeName).clear();
+      }
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+
+  // Same helpers as MemoryAdapter
+  _matchesWhere(event, where) {
+    for (const [key, value] of Object.entries(where)) {
+      const eventValue = this._getNestedValue(event, key);
+
+      if (Array.isArray(value)) {
+        if (!value.includes(eventValue)) return false;
+      } else if (typeof value === 'object' && value !== null) {
+        if (value.$gt !== undefined && !(eventValue > value.$gt)) return false;
+        if (value.$gte !== undefined && !(eventValue >= value.$gte)) return false;
+        if (value.$lt !== undefined && !(eventValue < value.$lt)) return false;
+        if (value.$lte !== undefined && !(eventValue <= value.$lte)) return false;
+        if (value.$ne !== undefined && eventValue === value.$ne) return false;
+      } else {
+        const normalizedEvent = typeof eventValue === 'string' ? eventValue.toLowerCase() : eventValue;
+        const normalizedValue = typeof value === 'string' ? value.toLowerCase() : value;
+        if (normalizedEvent !== normalizedValue) return false;
+      }
+    }
+    return true;
+  }
+
+  _getNestedValue(obj, path) {
+    if (path.startsWith('indexed.')) {
+      return obj.indexed?.[path.slice(8)];
+    }
+    if (path.startsWith('data.')) {
+      return obj.data?.[path.slice(5)];
+    }
+
+    if (obj.indexed?.[path] !== undefined) return obj.indexed[path];
+    if (obj.data?.[path] !== undefined) return obj.data[path];
+    return obj[path];
+  }
+}
+
+export default IndexedDBAdapter;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/storage/IndexedDBAdapter.js
+git commit -m "feat(storage): add IndexedDBAdapter for persistent event storage"
+```
+
+---
+
+## Task 4: Storage Index Export
+
+**Files:**
+- Create: `src/storage/index.js`
+
+**Step 1: Create storage module exports**
+
+```javascript
+// src/storage/index.js
+
+import StorageAdapter from './StorageAdapter.js';
+import IndexedDBAdapter from './IndexedDBAdapter.js';
+import MemoryAdapter from './MemoryAdapter.js';
+
+/**
+ * Select appropriate storage adapter based on config and environment.
+ * @param {Object} config - Persistence configuration
+ * @returns {StorageAdapter}
+ */
+function selectAdapter(config) {
+  // Explicit memory mode
+  if (config?.type === 'memory') {
+    return new MemoryAdapter();
+  }
+
+  // Check IndexedDB availability
+  if (typeof indexedDB !== 'undefined') {
+    return new IndexedDBAdapter();
+  }
+
+  // Fallback to memory
+  console.warn('[EventIndexer] IndexedDB not available, falling back to memory storage');
+  return new MemoryAdapter();
+}
+
+export {
+  StorageAdapter,
+  IndexedDBAdapter,
+  MemoryAdapter,
+  selectAdapter
+};
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/storage/index.js
+git commit -m "feat(storage): add storage module exports with adapter selection"
+```
+
+---
+
+## Task 5: Query Engine
+
+**Files:**
+- Create: `src/indexer/QueryEngine.js`
+
+**Step 1: Implement QueryEngine**
+
+```javascript
+// src/indexer/QueryEngine.js
+
+/**
+ * Query engine for EventIndexer.
+ * Provides the Events API for direct event access.
+ */
+class QueryEngine {
+  constructor(storage, eventBus) {
+    this.storage = storage;
+    this.eventBus = eventBus;
+    this.subscriptions = new Map(); // subscriptionId -> { eventTypes, callback, where }
+    this.nextSubscriptionId = 1;
+  }
+
+  /**
+   * Query events with filters.
+   * @param {string} eventName - Event type to query
+   * @param {QueryOptions} options - Query options
+   * @returns {Promise<QueryResult>}
+   */
+  async query(eventName, options = {}) {
+    return this.storage.queryEvents(eventName, {
+      where: options.where,
+      orderBy: options.orderBy || 'blockNumber',
+      order: options.order || 'desc',
+      limit: options.limit || 100,
+      offset: options.offset || 0
+    });
+  }
+
+  /**
+   * Get single event by ID.
+   * @param {string} eventName - Event type
+   * @param {string} id - Event ID (txHash-logIndex)
+   * @returns {Promise<IndexedEvent|null>}
+   */
+  async get(eventName, id) {
+    return this.storage.getEvent(eventName, id);
+  }
+
+  /**
+   * Subscribe to new events.
+   * @param {string|string[]} eventNames - Event type(s) to subscribe to
+   * @param {Function} callback - Called with new events
+   * @returns {Function} Unsubscribe function
+   */
+  subscribe(eventNames, callback) {
+    const types = Array.isArray(eventNames) ? eventNames : [eventNames];
+    const subscriptionId = this.nextSubscriptionId++;
+
+    this.subscriptions.set(subscriptionId, {
+      eventTypes: new Set(types),
+      callback
+    });
+
+    // Return unsubscribe function
+    return () => {
+      this.subscriptions.delete(subscriptionId);
+    };
+  }
+
+  /**
+   * Count events matching filter.
+   * @param {string} eventName - Event type
+   * @param {Object} where - Filter conditions
+   * @returns {Promise<number>}
+   */
+  async count(eventName, where) {
+    return this.storage.countEvents(eventName, where);
+  }
+
+  /**
+   * Called by SyncEngine when new events are indexed.
+   * Notifies subscribers.
+   * @param {string} eventType - Event type
+   * @param {IndexedEvent[]} events - New events
+   */
+  notifyNewEvents(eventType, events) {
+    for (const subscription of this.subscriptions.values()) {
+      if (subscription.eventTypes.has(eventType) || subscription.eventTypes.has('*')) {
+        try {
+          subscription.callback(events);
+        } catch (error) {
+          console.error('[QueryEngine] Subscription callback error:', error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Get all events for entity resolution (used by EntityResolver).
+   * Returns a lightweight checker interface.
+   * @param {Object} relatedWhere - Filter for related events
+   * @returns {Promise<EventChecker>}
+   */
+  async getEventChecker(relatedWhere = {}) {
+    // Pre-fetch all potentially related events
+    const eventCache = new Map();
+
+    return {
+      has: (eventName, where = {}) => {
+        const events = this._getCachedEvents(eventCache, eventName);
+        return events.some(e => this._matchesWhere(e, { ...relatedWhere, ...where }));
+      },
+
+      get: (eventName, where = {}) => {
+        const events = this._getCachedEvents(eventCache, eventName);
+        return events.filter(e => this._matchesWhere(e, { ...relatedWhere, ...where }));
+      },
+
+      count: (eventName, where = {}) => {
+        const events = this._getCachedEvents(eventCache, eventName);
+        return events.filter(e => this._matchesWhere(e, { ...relatedWhere, ...where })).length;
+      },
+
+      // Async method to prefetch events for a set of keys
+      prefetch: async (eventNames) => {
+        for (const eventName of eventNames) {
+          if (!eventCache.has(eventName)) {
+            const result = await this.storage.queryEvents(eventName, { limit: 10000 });
+            eventCache.set(eventName, result.events);
+          }
+        }
+      }
+    };
+  }
+
+  _getCachedEvents(cache, eventName) {
+    return cache.get(eventName) || [];
+  }
+
+  _matchesWhere(event, where) {
+    for (const [key, value] of Object.entries(where)) {
+      const eventValue = this._getNestedValue(event, key);
+      const normalizedEvent = typeof eventValue === 'string' ? eventValue.toLowerCase() : eventValue;
+      const normalizedValue = typeof value === 'string' ? value.toLowerCase() : value;
+      if (normalizedEvent !== normalizedValue) return false;
+    }
+    return true;
+  }
+
+  _getNestedValue(obj, path) {
+    if (obj.indexed?.[path] !== undefined) return obj.indexed[path];
+    if (obj.data?.[path] !== undefined) return obj.data[path];
+    return obj[path];
+  }
+}
+
+export default QueryEngine;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/indexer/QueryEngine.js
+git commit -m "feat(indexer): add QueryEngine for event queries and subscriptions"
+```
+
+---
+
+## Task 6: Sync Engine
+
+**Files:**
+- Create: `src/indexer/SyncEngine.js`
+
+**Step 1: Implement SyncEngine**
+
+```javascript
+// src/indexer/SyncEngine.js
+
+/**
+ * Sync engine for EventIndexer.
+ * Handles historical sync, real-time updates, and reorg recovery.
+ */
+class SyncEngine {
+  constructor(storage, queryEngine, eventBus, config = {}) {
+    this.storage = storage;
+    this.queryEngine = queryEngine;
+    this.eventBus = eventBus;
+
+    // Configuration with defaults
+    this.batchSize = config.batchSize || 2000;
+    this.confirmations = config.confirmations || 2;
+    this.realTimeEnabled = config.realTimeEnabled !== false;
+    this.retryAttempts = config.retryAttempts || 3;
+    this.retryDelay = config.retryDelay || 1000;
+    this.pollInterval = config.pollInterval || 12000;
+    this.reorgTracking = config.reorgTracking || false; // Full reorg tracking (optional)
+    this.reorgDepth = config.reorgDepth || 100; // How many blocks to track
+
+    // State
+    this.provider = null;
+    this.contract = null;
+    this.eventTypes = [];
+    this.deployBlock = 0;
+    this.chainId = null;
+
+    this.state = 'initializing'; // initializing | syncing | synced | paused | error
+    this.currentBlock = 0;
+    this.latestBlock = 0;
+    this.eventsIndexed = 0;
+    this.lastSyncTime = null;
+    this.error = null;
+
+    // Real-time sync
+    this.eventListeners = [];
+    this.pollTimer = null;
+    this.isPaused = false;
+
+    // Reorg tracking (optional)
+    this.recentBlocks = new Map(); // blockNumber -> blockHash
+  }
+
+  /**
+   * Initialize sync engine.
+   * @param {Object} params
+   * @param {ethers.Provider} params.provider - Ethereum provider
+   * @param {ethers.Contract} params.contract - Contract instance
+   * @param {Object[]} params.eventTypes - Event types from ABI
+   * @param {number} params.deployBlock - Starting block
+   * @param {number} params.chainId - Chain ID
+   */
+  async initialize({ provider, contract, eventTypes, deployBlock, chainId }) {
+    this.provider = provider;
+    this.contract = contract;
+    this.eventTypes = eventTypes;
+    this.deployBlock = deployBlock;
+    this.chainId = chainId;
+
+    // Validate chain ID matches stored data
+    await this._validateChainId();
+
+    // Load sync state
+    const syncState = await this.storage.getSyncState();
+    if (syncState) {
+      this.currentBlock = syncState.lastSyncedBlock;
+      this.eventsIndexed = Object.values(syncState.eventCounts || {}).reduce((a, b) => a + b, 0);
+      this.lastSyncTime = syncState.lastSyncTime;
+    } else {
+      this.currentBlock = this.deployBlock - 1;
+    }
+  }
+
+  async _validateChainId() {
+    const syncState = await this.storage.getSyncState();
+    if (syncState && syncState.chainId !== this.chainId) {
+      console.warn('[SyncEngine] Chain ID mismatch, clearing data');
+      await this.storage.clear();
+    }
+  }
+
+  /**
+   * Start syncing.
+   */
+  async start() {
+    if (this.state === 'synced' || this.state === 'syncing') return;
+
+    try {
+      // Historical sync
+      await this._syncHistorical();
+
+      // Start real-time sync
+      if (this.realTimeEnabled && !this.isPaused) {
+        await this._startRealTimeSync();
+      }
+    } catch (error) {
+      this.state = 'error';
+      this.error = error;
+      this.eventBus.emit('indexer:error', {
+        code: 'SYNC_ERROR',
+        message: error.message,
+        cause: error,
+        recoverable: true
+      });
+    }
+  }
+
+  async _syncHistorical() {
+    this.state = 'syncing';
+    this.latestBlock = await this.provider.getBlockNumber();
+
+    // Account for confirmations
+    const targetBlock = this.latestBlock - this.confirmations;
+
+    if (this.currentBlock >= targetBlock) {
+      this.state = 'synced';
+      this.eventBus.emit('indexer:syncComplete', {
+        eventsIndexed: this.eventsIndexed,
+        duration: 0
+      });
+      return;
+    }
+
+    const startTime = Date.now();
+    const startBlock = this.currentBlock + 1;
+
+    this.eventBus.emit('indexer:syncStarted', {
+      fromBlock: startBlock,
+      toBlock: targetBlock
+    });
+
+    // Process in batches
+    for (let fromBlock = startBlock; fromBlock <= targetBlock; fromBlock += this.batchSize) {
+      if (this.isPaused) break;
+
+      const toBlock = Math.min(fromBlock + this.batchSize - 1, targetBlock);
+
+      await this._syncBatch(fromBlock, toBlock);
+
+      // Emit progress
+      const progress = (toBlock - startBlock + 1) / (targetBlock - startBlock + 1);
+      this.eventBus.emit('indexer:syncProgress', {
+        progress,
+        currentBlock: toBlock,
+        latestBlock: this.latestBlock,
+        eventsIndexed: this.eventsIndexed
+      });
+    }
+
+    if (!this.isPaused) {
+      this.state = 'synced';
+      this.lastSyncTime = Date.now();
+
+      this.eventBus.emit('indexer:syncComplete', {
+        eventsIndexed: this.eventsIndexed,
+        duration: Date.now() - startTime
+      });
+    }
+  }
+
+  async _syncBatch(fromBlock, toBlock) {
+    const events = await this._fetchEventsWithRetry(fromBlock, toBlock);
+
+    if (events.length > 0) {
+      // Parse and index events
+      const indexedEvents = events.map(e => this._parseEvent(e));
+      await this.storage.putEvents(indexedEvents);
+      this.eventsIndexed += indexedEvents.length;
+
+      // Notify query engine
+      const eventsByType = this._groupByType(indexedEvents);
+      for (const [type, typeEvents] of Object.entries(eventsByType)) {
+        this.queryEngine.notifyNewEvents(type, typeEvents);
+      }
+    }
+
+    // Update sync state
+    this.currentBlock = toBlock;
+    await this._saveSyncState();
+  }
+
+  async _fetchEventsWithRetry(fromBlock, toBlock) {
+    for (let attempt = 0; attempt < this.retryAttempts; attempt++) {
+      try {
+        // Query all event types
+        const allEvents = [];
+        for (const eventType of this.eventTypes) {
+          const filter = this.contract.filters[eventType.name]();
+          const events = await this.contract.queryFilter(filter, fromBlock, toBlock);
+          allEvents.push(...events);
+        }
+        return allEvents;
+      } catch (error) {
+        if (attempt === this.retryAttempts - 1) throw error;
+
+        // Exponential backoff
+        const delay = this.retryDelay * Math.pow(2, attempt);
+        await this._sleep(delay);
+      }
+    }
+    return [];
+  }
+
+  _parseEvent(rawEvent) {
+    // Extract indexed and non-indexed params
+    const indexed = {};
+    const data = {};
+
+    if (rawEvent.args) {
+      const eventFragment = rawEvent.eventFragment ||
+        this.contract.interface.getEvent(rawEvent.event);
+
+      if (eventFragment) {
+        for (let i = 0; i < eventFragment.inputs.length; i++) {
+          const input = eventFragment.inputs[i];
+          const value = rawEvent.args[i];
+          const serialized = this._serializeValue(value);
+
+          if (input.indexed) {
+            indexed[input.name] = serialized;
+          }
+          data[input.name] = serialized;
+        }
+      }
+    }
+
+    return {
+      id: `${rawEvent.transactionHash}-${rawEvent.logIndex}`,
+      type: rawEvent.event,
+      blockNumber: rawEvent.blockNumber,
+      blockHash: rawEvent.blockHash,
+      transactionHash: rawEvent.transactionHash,
+      logIndex: rawEvent.logIndex,
+      timestamp: 0, // Will be filled by block data if available
+      data,
+      indexed
+    };
+  }
+
+  _serializeValue(value) {
+    if (value === null || value === undefined) return null;
+    if (typeof value === 'bigint' || value._isBigNumber) {
+      return value.toString();
+    }
+    if (Array.isArray(value)) {
+      return value.map(v => this._serializeValue(v));
+    }
+    return value;
+  }
+
+  _groupByType(events) {
+    const grouped = {};
+    for (const event of events) {
+      if (!grouped[event.type]) {
+        grouped[event.type] = [];
+      }
+      grouped[event.type].push(event);
+    }
+    return grouped;
+  }
+
+  async _saveSyncState() {
+    await this.storage.setSyncState({
+      lastSyncedBlock: this.currentBlock,
+      lastSyncTime: Date.now(),
+      eventCounts: {}, // Could track per-type counts
+      chainId: this.chainId
+    });
+  }
+
+  async _startRealTimeSync() {
+    // Try WebSocket subscription first
+    try {
+      for (const eventType of this.eventTypes) {
+        const filter = this.contract.filters[eventType.name]();
+        const listener = async (...args) => {
+          const event = args[args.length - 1]; // Last arg is the event object
+          await this._handleNewEvent(event);
+        };
+
+        this.contract.on(filter, listener);
+        this.eventListeners.push({ filter, listener });
+      }
+    } catch (error) {
+      // Fall back to polling
+      console.warn('[SyncEngine] WebSocket subscription failed, falling back to polling');
+      this._startPolling();
+    }
+
+    // Also start polling as backup (handles missed events)
+    this._startPolling();
+  }
+
+  _startPolling() {
+    if (this.pollTimer) return;
+
+    this.pollTimer = setInterval(async () => {
+      if (this.isPaused) return;
+
+      try {
+        const latestBlock = await this.provider.getBlockNumber();
+        const targetBlock = latestBlock - this.confirmations;
+
+        if (targetBlock > this.currentBlock) {
+          await this._syncBatch(this.currentBlock + 1, targetBlock);
+        }
+
+        this.latestBlock = latestBlock;
+
+        // Optional: reorg tracking
+        if (this.reorgTracking) {
+          await this._checkForReorg(latestBlock);
+        }
+      } catch (error) {
+        console.error('[SyncEngine] Polling error:', error);
+      }
+    }, this.pollInterval);
+  }
+
+  async _handleNewEvent(rawEvent) {
+    // Wait for confirmations
+    if (this.confirmations > 0) {
+      await this._waitForConfirmations(rawEvent.transactionHash);
+    }
+
+    const indexedEvent = this._parseEvent(rawEvent);
+    await this.storage.putEvents([indexedEvent]);
+    this.eventsIndexed++;
+
+    // Update current block if this event is ahead
+    if (indexedEvent.blockNumber > this.currentBlock) {
+      this.currentBlock = indexedEvent.blockNumber;
+      await this._saveSyncState();
+    }
+
+    // Notify
+    this.queryEngine.notifyNewEvents(indexedEvent.type, [indexedEvent]);
+    this.eventBus.emit('indexer:newEvents', {
+      eventType: indexedEvent.type,
+      events: [indexedEvent]
+    });
+  }
+
+  async _waitForConfirmations(txHash) {
+    let confirmations = 0;
+    while (confirmations < this.confirmations) {
+      const receipt = await this.provider.getTransactionReceipt(txHash);
+      if (!receipt) {
+        await this._sleep(1000);
+        continue;
+      }
+
+      const currentBlock = await this.provider.getBlockNumber();
+      confirmations = currentBlock - receipt.blockNumber + 1;
+
+      if (confirmations < this.confirmations) {
+        await this._sleep(1000);
+      }
+    }
+  }
+
+  async _checkForReorg(currentBlock) {
+    const block = await this.provider.getBlock(currentBlock);
+    if (!block) return;
+
+    // Check if parent hash matches what we stored
+    const storedParentHash = this.recentBlocks.get(currentBlock - 1);
+    if (storedParentHash && storedParentHash !== block.parentHash) {
+      // Reorg detected!
+      await this._handleReorg(currentBlock - 1);
+    }
+
+    // Track this block
+    this.recentBlocks.set(currentBlock, block.hash);
+
+    // Prune old entries
+    if (this.recentBlocks.size > this.reorgDepth) {
+      const oldest = Math.min(...this.recentBlocks.keys());
+      this.recentBlocks.delete(oldest);
+    }
+  }
+
+  async _handleReorg(forkBlock) {
+    // Find common ancestor
+    let checkBlock = forkBlock;
+    while (checkBlock > this.deployBlock) {
+      const storedHash = this.recentBlocks.get(checkBlock);
+      const chainBlock = await this.provider.getBlock(checkBlock);
+
+      if (storedHash === chainBlock?.hash) break;
+      checkBlock--;
+    }
+
+    // Delete events from orphaned blocks
+    await this.storage.deleteEventsAfterBlock(checkBlock);
+
+    // Update sync state
+    this.currentBlock = checkBlock;
+    await this._saveSyncState();
+
+    // Emit reorg event
+    this.eventBus.emit('indexer:reorg', {
+      forkBlock,
+      commonAncestor: checkBlock,
+      depth: forkBlock - checkBlock
+    });
+
+    // Re-sync from common ancestor
+    await this._syncHistorical();
+  }
+
+  /**
+   * Pause real-time sync.
+   */
+  pause() {
+    this.isPaused = true;
+    this.state = 'paused';
+    this.eventBus.emit('indexer:paused', {});
+  }
+
+  /**
+   * Resume real-time sync.
+   */
+  resume() {
+    this.isPaused = false;
+    this.start();
+    this.eventBus.emit('indexer:resumed', {});
+  }
+
+  /**
+   * Force re-sync from block.
+   * @param {number} fromBlock - Block to start from (default: deployBlock)
+   */
+  async resync(fromBlock) {
+    this.pause();
+
+    if (fromBlock !== undefined) {
+      this.currentBlock = fromBlock - 1;
+    } else {
+      this.currentBlock = this.deployBlock - 1;
+    }
+
+    await this.storage.clear();
+    await this._saveSyncState();
+
+    this.eventsIndexed = 0;
+    this.resume();
+  }
+
+  /**
+   * Get current sync status.
+   * @returns {SyncStatus}
+   */
+  getStatus() {
+    return {
+      state: this.state,
+      currentBlock: this.currentBlock,
+      latestBlock: this.latestBlock,
+      progress: this.latestBlock > 0
+        ? Math.min(1, (this.currentBlock - this.deployBlock) / (this.latestBlock - this.deployBlock))
+        : 0,
+      eventsIndexed: this.eventsIndexed,
+      lastSyncTime: this.lastSyncTime,
+      error: this.error
+    };
+  }
+
+  /**
+   * Stop sync and cleanup.
+   */
+  async stop() {
+    this.isPaused = true;
+
+    // Remove event listeners
+    for (const { filter, listener } of this.eventListeners) {
+      this.contract.off(filter, listener);
+    }
+    this.eventListeners = [];
+
+    // Stop polling
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+export default SyncEngine;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/indexer/SyncEngine.js
+git commit -m "feat(indexer): add SyncEngine for historical and real-time sync"
+```
+
+---
+
+## Task 7: Entity Resolver
+
+**Files:**
+- Create: `src/indexer/EntityResolver.js`
+
+**Step 1: Implement EntityResolver**
+
+```javascript
+// src/indexer/EntityResolver.js
+
+/**
+ * Entity resolver for EventIndexer.
+ * Provides the Entities API for domain-level queries.
+ */
+class EntityResolver {
+  constructor(queryEngine, entityDefinitions = {}) {
+    this.queryEngine = queryEngine;
+    this.definitions = entityDefinitions;
+    this.entityAPIs = {};
+
+    // Create API for each entity
+    for (const [name, definition] of Object.entries(entityDefinitions)) {
+      this.entityAPIs[name] = this._createEntityAPI(name, definition);
+    }
+  }
+
+  /**
+   * Get entity API by name.
+   * @param {string} name - Entity name
+   * @returns {EntityQueryable}
+   */
+  getEntity(name) {
+    return this.entityAPIs[name];
+  }
+
+  /**
+   * Get all entity APIs (for proxy access).
+   * @returns {Object}
+   */
+  getAllEntities() {
+    return this.entityAPIs;
+  }
+
+  _createEntityAPI(name, definition) {
+    const self = this;
+
+    return {
+      /**
+       * Query entities.
+       * @param {EntityWhereClause} where - Filter conditions
+       * @returns {Promise<Entity[]>}
+       */
+      async query(where = {}) {
+        return self._queryEntities(name, definition, where);
+      },
+
+      /**
+       * Get single entity by key.
+       * @param {string|number} key - Entity key value
+       * @returns {Promise<Entity|null>}
+       */
+      async get(key) {
+        const entities = await self._queryEntities(name, definition, {
+          [definition.key]: key
+        });
+        return entities[0] || null;
+      },
+
+      /**
+       * Subscribe to entity changes.
+       * @param {EntityWhereClause} where - Filter conditions
+       * @param {Function} callback - Called when entities change
+       * @returns {Function} Unsubscribe function
+       */
+      subscribe(where, callback) {
+        // Subscribe to source event and related events
+        const eventTypes = self._getRelevantEventTypes(definition);
+
+        return self.queryEngine.subscribe(eventTypes, async () => {
+          const entities = await self._queryEntities(name, definition, where);
+          callback(entities);
+        });
+      },
+
+      /**
+       * Count entities.
+       * @param {EntityWhereClause} where - Filter conditions
+       * @returns {Promise<number>}
+       */
+      async count(where = {}) {
+        const entities = await self._queryEntities(name, definition, where);
+        return entities.length;
+      }
+    };
+  }
+
+  async _queryEntities(name, definition, where = {}) {
+    // Separate status filter from direct filters
+    const statusFilter = where.status;
+    const directFilters = { ...where };
+    delete directFilters.status;
+
+    // Query source events
+    const sourceResult = await this.queryEngine.query(definition.source, {
+      where: directFilters,
+      limit: 10000 // Get all matching source events
+    });
+
+    // Get event checker for status/computed evaluation
+    const eventChecker = await this.queryEngine.getEventChecker();
+
+    // Prefetch events needed for status evaluation
+    const relevantEventTypes = this._getRelevantEventTypes(definition);
+    await eventChecker.prefetch(relevantEventTypes);
+
+    // Build entities from source events
+    const entities = [];
+    for (const sourceEvent of sourceResult.events) {
+      const entity = await this._buildEntity(name, definition, sourceEvent, eventChecker);
+
+      // Apply status filter
+      if (statusFilter && entity.status !== statusFilter) {
+        continue;
+      }
+
+      entities.push(entity);
+    }
+
+    return entities;
+  }
+
+  async _buildEntity(name, definition, sourceEvent, eventChecker) {
+    const entity = {
+      _type: name,
+      _sourceEvent: sourceEvent,
+      ...sourceEvent.data
+    };
+
+    // Add key field explicitly
+    entity[definition.key] = sourceEvent.data[definition.key] || sourceEvent.indexed[definition.key];
+
+    // Evaluate status
+    if (definition.status) {
+      entity.status = this._evaluateStatus(entity, definition.status, eventChecker);
+    }
+
+    // Evaluate computed fields
+    if (definition.computed) {
+      for (const [fieldName, computeFn] of Object.entries(definition.computed)) {
+        try {
+          entity[fieldName] = computeFn(entity, eventChecker);
+        } catch (error) {
+          console.error(`[EntityResolver] Error computing ${fieldName}:`, error);
+          entity[fieldName] = null;
+        }
+      }
+    }
+
+    // Resolve relations (lazy - only resolve when accessed)
+    if (definition.relations) {
+      for (const [relationName, relationDef] of Object.entries(definition.relations)) {
+        Object.defineProperty(entity, relationName, {
+          get: () => this._resolveRelation(entity, relationDef),
+          enumerable: true
+        });
+      }
+    }
+
+    return entity;
+  }
+
+  _evaluateStatus(entity, statusDef, eventChecker) {
+    // Check each status condition in order
+    for (const [statusName, condition] of Object.entries(statusDef)) {
+      if (statusName === 'default') continue;
+
+      try {
+        if (condition(entity, eventChecker)) {
+          return statusName;
+        }
+      } catch (error) {
+        console.error(`[EntityResolver] Error evaluating status ${statusName}:`, error);
+      }
+    }
+
+    return statusDef.default || 'unknown';
+  }
+
+  async _resolveRelation(entity, relationDef) {
+    const relatedEntity = this.entityAPIs[relationDef.entity];
+    if (!relatedEntity) return null;
+
+    const foreignKeyValue = entity[relationDef.foreignKey];
+    if (foreignKeyValue === undefined) return null;
+
+    if (relationDef.type === 'many') {
+      return relatedEntity.query({ [relationDef.foreignKey]: foreignKeyValue });
+    } else {
+      return relatedEntity.get(foreignKeyValue);
+    }
+  }
+
+  _getRelevantEventTypes(definition) {
+    const types = new Set([definition.source]);
+
+    // Add events referenced in status conditions
+    if (definition.status) {
+      for (const condition of Object.values(definition.status)) {
+        if (typeof condition === 'function') {
+          // Try to extract event names from function source
+          // This is a best-effort heuristic
+          const fnStr = condition.toString();
+          const matches = fnStr.match(/events\.has\(['"](\w+)['"]/g) || [];
+          for (const match of matches) {
+            const eventName = match.match(/['"](\w+)['"]/)?.[1];
+            if (eventName) types.add(eventName);
+          }
+        }
+      }
+    }
+
+    return Array.from(types);
+  }
+}
+
+export default EntityResolver;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/indexer/EntityResolver.js
+git commit -m "feat(indexer): add EntityResolver for domain-level entity queries"
+```
+
+---
+
+## Task 8: Patterns API
+
+**Files:**
+- Create: `src/indexer/Patterns.js`
+
+**Step 1: Implement Patterns**
+
+```javascript
+// src/indexer/Patterns.js
+
+/**
+ * Pre-built patterns for common dApp needs.
+ * Zero-config solutions for activity feeds, leaderboards, etc.
+ */
+class Patterns {
+  constructor(queryEngine, entityResolver) {
+    this.queryEngine = queryEngine;
+    this.entityResolver = entityResolver;
+  }
+
+  /**
+   * User activity feed.
+   * @param {string} address - User address
+   * @param {Object} options - Options
+   * @param {string[]} options.events - Event types to include
+   * @param {string[]} options.userFields - Fields to match address against (auto-detected if omitted)
+   * @param {number} options.limit - Max results
+   * @param {number} options.offset - Skip N results
+   * @returns {Promise<ActivityItem[]>}
+   */
+  async userActivity(address, options = {}) {
+    const { events = [], userFields, limit = 50, offset = 0 } = options;
+    const normalizedAddress = address.toLowerCase();
+
+    // Collect activity from all event types
+    const allActivity = [];
+
+    for (const eventType of events) {
+      const result = await this.queryEngine.query(eventType, {
+        limit: 1000 // Get more to filter
+      });
+
+      // Auto-detect user fields if not specified
+      const fields = userFields || this._detectAddressFields(result.events[0]);
+
+      // Filter events involving this user
+      for (const event of result.events) {
+        const isUserEvent = fields.some(field => {
+          const value = event.indexed[field] || event.data[field];
+          return typeof value === 'string' && value.toLowerCase() === normalizedAddress;
+        });
+
+        if (isUserEvent) {
+          allActivity.push({
+            type: event.type,
+            timestamp: event.timestamp || event.blockNumber, // Fall back to block number
+            blockNumber: event.blockNumber,
+            transactionHash: event.transactionHash,
+            data: event.data
+          });
+        }
+      }
+    }
+
+    // Sort by timestamp/block descending
+    allActivity.sort((a, b) => (b.timestamp || b.blockNumber) - (a.timestamp || a.blockNumber));
+
+    // Paginate
+    return allActivity.slice(offset, offset + limit);
+  }
+
+  /**
+   * Find refundable items (cancelled parent + unclaimed).
+   * @param {Object} options - Options
+   * @param {string} options.itemEvent - Event creating the item
+   * @param {string} options.itemKey - Unique key field
+   * @param {string} options.parentKey - Field linking to parent
+   * @param {string} options.cancelEvent - Event that cancels parent
+   * @param {string} options.claimEvent - Event that claims item
+   * @param {string} options.userField - Field containing user address
+   * @param {string} options.user - User address to filter
+   * @returns {Promise<IndexedEvent[]>}
+   */
+  async refundable(options) {
+    const {
+      itemEvent,
+      itemKey,
+      parentKey,
+      cancelEvent,
+      claimEvent,
+      userField,
+      user
+    } = options;
+
+    const normalizedUser = user.toLowerCase();
+
+    // Get all items for user
+    const itemsResult = await this.queryEngine.query(itemEvent, { limit: 10000 });
+    const userItems = itemsResult.events.filter(e => {
+      const userValue = e.indexed[userField] || e.data[userField];
+      return typeof userValue === 'string' && userValue.toLowerCase() === normalizedUser;
+    });
+
+    // Get cancelled parents
+    const cancelResult = await this.queryEngine.query(cancelEvent, { limit: 10000 });
+    const cancelledParents = new Set(
+      cancelResult.events.map(e => e.indexed[parentKey] || e.data[parentKey])
+    );
+
+    // Get claimed items
+    const claimResult = await this.queryEngine.query(claimEvent, { limit: 10000 });
+    const claimedItems = new Set(
+      claimResult.events.map(e => e.indexed[itemKey] || e.data[itemKey])
+    );
+
+    // Filter: parent cancelled AND item not claimed
+    return userItems.filter(item => {
+      const itemKeyValue = item.indexed[itemKey] || item.data[itemKey];
+      const parentKeyValue = item.indexed[parentKey] || item.data[parentKey];
+
+      return cancelledParents.has(parentKeyValue) && !claimedItems.has(itemKeyValue);
+    });
+  }
+
+  /**
+   * Leaderboard aggregation.
+   * @param {Object} options - Options
+   * @param {string} options.event - Event to aggregate
+   * @param {string} options.groupBy - Field to group by
+   * @param {string} options.aggregate - 'count' or 'sum'
+   * @param {string} options.sumField - Field to sum (if aggregate: 'sum')
+   * @param {number} options.limit - Max results
+   * @param {Object} options.where - Filter conditions
+   * @returns {Promise<LeaderboardEntry[]>}
+   */
+  async leaderboard(options) {
+    const { event, groupBy, aggregate, sumField, limit = 10, where } = options;
+
+    const result = await this.queryEngine.query(event, {
+      where,
+      limit: 10000
+    });
+
+    // Group by field
+    const groups = new Map();
+    for (const e of result.events) {
+      const key = e.indexed[groupBy] || e.data[groupBy];
+      if (key === undefined) continue;
+
+      const normalizedKey = typeof key === 'string' ? key.toLowerCase() : key;
+
+      if (!groups.has(normalizedKey)) {
+        groups.set(normalizedKey, { key, events: [] });
+      }
+      groups.get(normalizedKey).events.push(e);
+    }
+
+    // Calculate aggregates
+    const entries = [];
+    for (const [normalizedKey, group] of groups) {
+      let value;
+      if (aggregate === 'count') {
+        value = group.events.length;
+      } else if (aggregate === 'sum') {
+        value = group.events.reduce((sum, e) => {
+          const fieldValue = e.indexed[sumField] || e.data[sumField];
+          const num = typeof fieldValue === 'string' ? parseFloat(fieldValue) : fieldValue;
+          return sum + (isNaN(num) ? 0 : num);
+        }, 0);
+      }
+
+      entries.push({ key: group.key, value });
+    }
+
+    // Sort by value descending
+    entries.sort((a, b) => b.value - a.value);
+
+    // Add ranks and limit
+    return entries.slice(0, limit).map((entry, index) => ({
+      ...entry,
+      rank: index + 1
+    }));
+  }
+
+  /**
+   * Time-series aggregation.
+   * @param {Object} options - Options
+   * @param {string} options.event - Event to aggregate
+   * @param {string} options.interval - 'hour' | 'day' | 'week'
+   * @param {string} options.aggregate - 'count' or 'sum'
+   * @param {string} options.sumField - Field to sum (if aggregate: 'sum')
+   * @param {Object} options.where - Filter conditions
+   * @param {number} options.periods - Number of periods (default: 30)
+   * @returns {Promise<TimeSeriesPoint[]>}
+   */
+  async timeSeries(options) {
+    const { event, interval, aggregate, sumField, where, periods = 30 } = options;
+
+    const result = await this.queryEngine.query(event, {
+      where,
+      limit: 100000
+    });
+
+    // Calculate interval in milliseconds
+    const intervalMs = {
+      hour: 60 * 60 * 1000,
+      day: 24 * 60 * 60 * 1000,
+      week: 7 * 24 * 60 * 60 * 1000
+    }[interval];
+
+    if (!intervalMs) {
+      throw new Error(`Invalid interval: ${interval}`);
+    }
+
+    // Group events by period
+    const now = Date.now();
+    const periodGroups = new Map();
+
+    // Initialize periods
+    for (let i = 0; i < periods; i++) {
+      const periodStart = now - (i + 1) * intervalMs;
+      const periodKey = new Date(periodStart).toISOString();
+      periodGroups.set(periodKey, []);
+    }
+
+    // Assign events to periods
+    for (const e of result.events) {
+      const eventTime = e.timestamp ? e.timestamp * 1000 : now; // Assume timestamp is in seconds
+      const periodsAgo = Math.floor((now - eventTime) / intervalMs);
+
+      if (periodsAgo >= 0 && periodsAgo < periods) {
+        const periodStart = now - (periodsAgo + 1) * intervalMs;
+        const periodKey = new Date(periodStart).toISOString();
+
+        if (periodGroups.has(periodKey)) {
+          periodGroups.get(periodKey).push(e);
+        }
+      }
+    }
+
+    // Calculate aggregates
+    const points = [];
+    for (const [period, events] of periodGroups) {
+      let value;
+      if (aggregate === 'count') {
+        value = events.length;
+      } else if (aggregate === 'sum') {
+        value = events.reduce((sum, e) => {
+          const fieldValue = e.indexed[sumField] || e.data[sumField];
+          const num = typeof fieldValue === 'string' ? parseFloat(fieldValue) : fieldValue;
+          return sum + (isNaN(num) ? 0 : num);
+        }, 0);
+      }
+
+      points.push({ period, value });
+    }
+
+    // Sort by period ascending (oldest first)
+    points.sort((a, b) => new Date(a.period) - new Date(b.period));
+
+    return points;
+  }
+
+  /**
+   * Detect address fields in an event.
+   * @param {IndexedEvent} event - Sample event
+   * @returns {string[]} Field names that look like addresses
+   */
+  _detectAddressFields(event) {
+    if (!event) return [];
+
+    const fields = [];
+    const allFields = { ...event.indexed, ...event.data };
+
+    for (const [key, value] of Object.entries(allFields)) {
+      if (typeof value === 'string' && value.match(/^0x[a-fA-F0-9]{40}$/)) {
+        fields.push(key);
+      }
+    }
+
+    return fields;
+  }
+}
+
+export default Patterns;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/indexer/Patterns.js
+git commit -m "feat(indexer): add Patterns API for activity feeds, leaderboards, time series"
+```
+
+---
+
+## Task 9: Indexer Module Export
+
+**Files:**
+- Create: `src/indexer/index.js`
+
+**Step 1: Create indexer module exports**
+
+```javascript
+// src/indexer/index.js
+
+import QueryEngine from './QueryEngine.js';
+import SyncEngine from './SyncEngine.js';
+import EntityResolver from './EntityResolver.js';
+import Patterns from './Patterns.js';
+
+export {
+  QueryEngine,
+  SyncEngine,
+  EntityResolver,
+  Patterns
+};
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/indexer/index.js
+git commit -m "feat(indexer): add indexer module exports"
+```
+
+---
+
+## Task 10: EventIndexer Service
+
+**Files:**
+- Create: `src/services/EventIndexer.js`
+
+**Step 1: Implement EventIndexer (main service)**
+
+```javascript
+// src/services/EventIndexer.js
+
+import { selectAdapter } from '../storage/index.js';
+import { QueryEngine, SyncEngine, EntityResolver, Patterns } from '../indexer/index.js';
+import { ethers } from 'ethers';
+
+/**
+ * Error types for EventIndexer.
+ */
+class EventIndexerError extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.name = 'EventIndexerError';
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+const ErrorCodes = {
+  NOT_INITIALIZED: 'NOT_INITIALIZED',
+  STORAGE_ERROR: 'STORAGE_ERROR',
+  SYNC_ERROR: 'SYNC_ERROR',
+  QUERY_ERROR: 'QUERY_ERROR',
+  INVALID_CONFIG: 'INVALID_CONFIG',
+  PROVIDER_ERROR: 'PROVIDER_ERROR',
+  REORG_DETECTED: 'REORG_DETECTED'
+};
+
+/**
+ * EventIndexer - Client-side event indexing for dApps.
+ *
+ * Provides three levels of abstraction:
+ * - Events: Raw indexed events with filtering
+ * - Entities: Domain objects derived from events
+ * - Patterns: Pre-built solutions (activity feeds, leaderboards)
+ */
+class EventIndexer {
+  /**
+   * Create EventIndexer instance.
+   * @param {EventBus} eventBus - microact EventBus instance
+   * @param {Object} options - Options
+   * @param {BlockchainService} options.blockchainService - For provider access (optional)
+   */
+  constructor(eventBus, options = {}) {
+    if (!eventBus) {
+      throw new EventIndexerError('EventBus is required', ErrorCodes.INVALID_CONFIG);
+    }
+
+    this.eventBus = eventBus;
+    this.blockchainService = options.blockchainService;
+
+    // Internal components (initialized in initialize())
+    this.storage = null;
+    this.queryEngine = null;
+    this.syncEngine = null;
+    this.entityResolver = null;
+    this.patternsAPI = null;
+    this.contract = null;
+
+    this.initialized = false;
+    this.config = null;
+  }
+
+  /**
+   * Initialize the EventIndexer.
+   * @param {EventIndexerConfig} config - Configuration
+   */
+  async initialize(config) {
+    this._validateConfig(config);
+    this.config = config;
+
+    try {
+      // Get provider
+      const provider = this._getProvider(config);
+
+      // Get chain ID
+      const network = await provider.getNetwork();
+      const chainId = Number(network.chainId);
+
+      // Extract event types from ABI
+      const eventTypes = this._extractEventTypes(config.contract.abi);
+
+      // Initialize storage
+      this.storage = selectAdapter(config.persistence);
+      await this.storage.initialize({
+        dbName: config.persistence?.dbName || `micro-web3-events-${chainId}`,
+        version: config.persistence?.version || 1,
+        eventTypes
+      });
+
+      // Create contract instance
+      this.contract = new ethers.Contract(
+        config.contract.address,
+        config.contract.abi,
+        provider
+      );
+
+      // Detect deploy block if not provided
+      const deployBlock = config.contract.deployBlock || await this._detectDeployBlock(provider);
+
+      // Initialize components
+      this.queryEngine = new QueryEngine(this.storage, this.eventBus);
+
+      this.syncEngine = new SyncEngine(
+        this.storage,
+        this.queryEngine,
+        this.eventBus,
+        config.sync || {}
+      );
+      await this.syncEngine.initialize({
+        provider,
+        contract: this.contract,
+        eventTypes,
+        deployBlock,
+        chainId
+      });
+
+      // Initialize entity resolver if entities defined
+      if (config.entities) {
+        this.entityResolver = new EntityResolver(this.queryEngine, config.entities);
+      }
+
+      // Initialize patterns
+      this.patternsAPI = new Patterns(this.queryEngine, this.entityResolver);
+
+      this.initialized = true;
+      this.eventBus.emit('indexer:initialized', {});
+
+      // Start syncing
+      await this.syncEngine.start();
+
+    } catch (error) {
+      this.eventBus.emit('indexer:error', {
+        code: ErrorCodes.STORAGE_ERROR,
+        message: `Initialization failed: ${error.message}`,
+        cause: error,
+        recoverable: false
+      });
+      throw new EventIndexerError(
+        `Failed to initialize EventIndexer: ${error.message}`,
+        ErrorCodes.STORAGE_ERROR,
+        error
+      );
+    }
+  }
+
+  _validateConfig(config) {
+    if (!config.contract) {
+      throw new EventIndexerError('contract config is required', ErrorCodes.INVALID_CONFIG);
+    }
+    if (!config.contract.address) {
+      throw new EventIndexerError('contract.address is required', ErrorCodes.INVALID_CONFIG);
+    }
+    if (!config.contract.abi || !Array.isArray(config.contract.abi)) {
+      throw new EventIndexerError('contract.abi is required and must be an array', ErrorCodes.INVALID_CONFIG);
+    }
+    if (!config.provider && !this.blockchainService) {
+      throw new EventIndexerError(
+        'Either provider in config or blockchainService in constructor is required',
+        ErrorCodes.INVALID_CONFIG
+      );
+    }
+  }
+
+  _getProvider(config) {
+    if (config.provider) {
+      return config.provider;
+    }
+    if (this.blockchainService?.getProvider) {
+      return this.blockchainService.getProvider();
+    }
+    if (this.blockchainService?.provider) {
+      return this.blockchainService.provider;
+    }
+    throw new EventIndexerError('No provider available', ErrorCodes.PROVIDER_ERROR);
+  }
+
+  _extractEventTypes(abi) {
+    const eventTypes = [];
+
+    for (const item of abi) {
+      if (item.type === 'event') {
+        const indexedParams = item.inputs
+          .filter(input => input.indexed)
+          .map(input => input.name);
+
+        eventTypes.push({
+          name: item.name,
+          inputs: item.inputs,
+          indexedParams
+        });
+      }
+    }
+
+    return eventTypes;
+  }
+
+  async _detectDeployBlock(provider) {
+    // Default to 0 if we can't detect
+    // In production, you'd want to either require this or use a heuristic
+    console.warn('[EventIndexer] No deployBlock specified, starting from block 0');
+    return 0;
+  }
+
+  /**
+   * Events API - Level 1 (Low-level)
+   * Direct access to raw indexed events.
+   */
+  get events() {
+    this._checkInitialized();
+    return {
+      query: (eventName, options) => this.queryEngine.query(eventName, options),
+      get: (eventName, id) => this.queryEngine.get(eventName, id),
+      subscribe: (eventNames, callback) => this.queryEngine.subscribe(eventNames, callback),
+      count: (eventName, where) => this.queryEngine.count(eventName, where)
+    };
+  }
+
+  /**
+   * Entities API - Level 2 (Domain-level)
+   * Access to domain objects derived from events.
+   * Returns proxy for entity.EntityName access pattern.
+   */
+  get entities() {
+    this._checkInitialized();
+
+    if (!this.entityResolver) {
+      console.warn('[EventIndexer] No entities configured');
+      return {};
+    }
+
+    return new Proxy({}, {
+      get: (target, prop) => {
+        return this.entityResolver.getEntity(prop);
+      }
+    });
+  }
+
+  /**
+   * Patterns API - Level 3 (Zero-config)
+   * Pre-built solutions for common needs.
+   */
+  get patterns() {
+    this._checkInitialized();
+    return this.patternsAPI;
+  }
+
+  /**
+   * Sync API - Control sync behavior.
+   */
+  get sync() {
+    this._checkInitialized();
+    return {
+      getStatus: () => this.syncEngine.getStatus(),
+      resync: (fromBlock) => this.syncEngine.resync(fromBlock),
+      clear: () => this.storage.clear(),
+      pause: () => this.syncEngine.pause(),
+      resume: () => this.syncEngine.resume()
+    };
+  }
+
+  _checkInitialized() {
+    if (!this.initialized) {
+      throw new EventIndexerError(
+        'EventIndexer not initialized. Call initialize() first.',
+        ErrorCodes.NOT_INITIALIZED
+      );
+    }
+  }
+
+  /**
+   * Cleanup and close connections.
+   */
+  async destroy() {
+    if (this.syncEngine) {
+      await this.syncEngine.stop();
+    }
+    if (this.storage) {
+      await this.storage.close();
+    }
+    this.initialized = false;
+  }
+}
+
+// Export error types for external use
+EventIndexer.EventIndexerError = EventIndexerError;
+EventIndexer.ErrorCodes = ErrorCodes;
+
+export default EventIndexer;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/services/EventIndexer.js
+git commit -m "feat(services): add EventIndexer main service orchestrating all components"
+```
+
+---
+
+## Task 11: Component Integration (useIndexer hook)
+
+**Files:**
+- Modify: `src/services/EventIndexer.js` (add static method for hook installation)
+
+**Step 1: Add useIndexer hook installer to EventIndexer**
+
+Add this method to the EventIndexer class (before the final export):
+
+```javascript
+// Add to EventIndexer class, before export
+
+  /**
+   * Install useIndexer hook on Component class.
+   * Call this once after importing your Component class.
+   *
+   * @param {typeof Component} ComponentClass - The Component class to extend
+   *
+   * @example
+   * import { Component } from '@monygroupcorp/microact';
+   * import { EventIndexer } from '@monygroupcorp/micro-web3';
+   * EventIndexer.installHook(Component);
+   */
+  static installHook(ComponentClass) {
+    if (ComponentClass.prototype.useIndexer) {
+      console.warn('[EventIndexer] useIndexer hook already installed');
+      return;
+    }
+
+    /**
+     * Reactive query hook for EventIndexer.
+     * Auto-updates when indexed events change.
+     *
+     * @param {EntityQueryable|EventsAPI} queryable - What to query (entity or events)
+     * @param {Object|Function} where - Filter conditions (can be reactive functions)
+     * @param {Object} options - Hook options
+     * @param {Function} options.onUpdate - Called when results change
+     * @param {Function} options.onError - Called on query error
+     * @returns {Proxy} Proxy that returns current results
+     */
+    ComponentClass.prototype.useIndexer = function(queryable, where = {}, options = {}) {
+      const self = this;
+      let result = null;
+      let isLoading = true;
+      let unsubscribe = null;
+
+      // Resolve reactive where values
+      const resolveWhere = () => {
+        const resolved = {};
+        for (const [key, value] of Object.entries(where)) {
+          resolved[key] = typeof value === 'function' ? value() : value;
+        }
+        return resolved;
+      };
+
+      // Execute query
+      const executeQuery = async () => {
+        try {
+          const whereValues = resolveWhere();
+
+          if (queryable.query) {
+            // Entity or events queryable
+            const queryResult = await queryable.query(whereValues);
+            result = Array.isArray(queryResult) ? queryResult : queryResult.events;
+          } else {
+            result = [];
+          }
+
+          isLoading = false;
+
+          if (options.onUpdate) {
+            options.onUpdate(result);
+          }
+        } catch (error) {
+          isLoading = false;
+          console.error('[useIndexer] Query error:', error);
+          if (options.onError) {
+            options.onError(error);
+          }
+        }
+      };
+
+      // Initial query
+      executeQuery();
+
+      // Subscribe to changes
+      if (queryable.subscribe) {
+        unsubscribe = queryable.subscribe(resolveWhere(), () => {
+          executeQuery();
+        });
+      }
+
+      // Register cleanup
+      if (this.registerCleanup) {
+        this.registerCleanup(() => {
+          if (unsubscribe) unsubscribe();
+        });
+      }
+
+      // Return proxy for array-like access
+      return new Proxy([], {
+        get(target, prop) {
+          if (prop === 'length') return result?.length || 0;
+          if (prop === 'isLoading') return isLoading;
+          if (prop === Symbol.iterator) {
+            return function* () {
+              if (result) yield* result;
+            };
+          }
+          if (typeof prop === 'string' && !isNaN(prop)) {
+            return result?.[parseInt(prop)];
+          }
+          // Array methods
+          if (result && typeof result[prop] === 'function') {
+            return result[prop].bind(result);
+          }
+          return result?.[prop];
+        }
+      });
+    };
+  }
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/services/EventIndexer.js
+git commit -m "feat(indexer): add useIndexer hook installer for reactive component queries"
+```
+
+---
+
+## Task 12: SyncProgressBar Component
+
+**Files:**
+- Create: `src/components/SyncProgressBar/SyncProgressBar.js`
+- Create: `src/components/SyncProgressBar/SyncProgressBar.css`
+
+**Step 1: Create SyncProgressBar component**
+
+```javascript
+// src/components/SyncProgressBar/SyncProgressBar.js
+
+/**
+ * SyncProgressBar - UI component showing indexer sync status.
+ *
+ * @example
+ * import { SyncProgressBar } from '@monygroupcorp/micro-web3/components';
+ * const progressBar = new SyncProgressBar({ indexer, eventBus });
+ * progressBar.mount(document.getElementById('sync-status'));
+ */
+class SyncProgressBar {
+  constructor({ indexer, eventBus }) {
+    if (!indexer) {
+      throw new Error('SyncProgressBar requires indexer instance');
+    }
+    if (!eventBus) {
+      throw new Error('SyncProgressBar requires eventBus instance');
+    }
+
+    this.indexer = indexer;
+    this.eventBus = eventBus;
+    this.element = null;
+    this.unsubscribers = [];
+
+    this.state = {
+      status: 'initializing',
+      progress: 0,
+      currentBlock: 0,
+      latestBlock: 0,
+      error: null
+    };
+  }
+
+  mount(container) {
+    if (typeof container === 'string') {
+      container = document.querySelector(container);
+    }
+    if (!container) {
+      throw new Error('SyncProgressBar: Invalid container');
+    }
+
+    // Create element
+    this.element = document.createElement('div');
+    this.element.className = 'mw3-sync-progress';
+    container.appendChild(this.element);
+
+    // Subscribe to events
+    this._setupListeners();
+
+    // Initial render
+    this._updateState(this.indexer.sync.getStatus());
+    this._render();
+
+    return this;
+  }
+
+  unmount() {
+    // Cleanup subscriptions
+    for (const unsub of this.unsubscribers) {
+      unsub();
+    }
+    this.unsubscribers = [];
+
+    // Remove element
+    if (this.element && this.element.parentNode) {
+      this.element.parentNode.removeChild(this.element);
+    }
+    this.element = null;
+  }
+
+  _setupListeners() {
+    const listeners = [
+      ['indexer:syncProgress', (data) => {
+        this._updateState({
+          status: 'syncing',
+          progress: data.progress,
+          currentBlock: data.currentBlock,
+          latestBlock: data.latestBlock
+        });
+      }],
+      ['indexer:syncComplete', () => {
+        this._updateState({ status: 'synced', progress: 1 });
+      }],
+      ['indexer:error', (data) => {
+        this._updateState({ status: 'error', error: data.message });
+      }],
+      ['indexer:paused', () => {
+        this._updateState({ status: 'paused' });
+      }],
+      ['indexer:resumed', () => {
+        this._updateState({ status: 'syncing' });
+      }]
+    ];
+
+    for (const [event, handler] of listeners) {
+      const unsub = this.eventBus.on(event, handler);
+      this.unsubscribers.push(unsub);
+    }
+  }
+
+  _updateState(updates) {
+    this.state = { ...this.state, ...updates };
+    this._render();
+  }
+
+  _render() {
+    if (!this.element) return;
+
+    const { status, progress, currentBlock, latestBlock, error } = this.state;
+
+    // Update class for state
+    this.element.className = `mw3-sync-progress mw3-sync-progress--${status}`;
+
+    if (status === 'syncing') {
+      const percent = Math.round(progress * 100);
+      this.element.innerHTML = `
+        <div class="mw3-sync-progress__bar" style="width: ${percent}%"></div>
+        <span class="mw3-sync-progress__text">Syncing... ${percent}%</span>
+      `;
+    } else if (status === 'synced') {
+      this.element.innerHTML = `
+        <span class="mw3-sync-progress__text">Synced to block ${latestBlock.toLocaleString()}</span>
+      `;
+    } else if (status === 'error') {
+      this.element.innerHTML = `
+        <span class="mw3-sync-progress__text">Sync failed: ${error || 'Unknown error'}</span>
+        <button class="mw3-sync-progress__retry">Retry</button>
+      `;
+
+      // Add retry handler
+      const retryBtn = this.element.querySelector('.mw3-sync-progress__retry');
+      if (retryBtn) {
+        retryBtn.onclick = () => this.indexer.sync.resync();
+      }
+    } else if (status === 'paused') {
+      this.element.innerHTML = `
+        <span class="mw3-sync-progress__text">Sync paused</span>
+        <button class="mw3-sync-progress__resume">Resume</button>
+      `;
+
+      const resumeBtn = this.element.querySelector('.mw3-sync-progress__resume');
+      if (resumeBtn) {
+        resumeBtn.onclick = () => this.indexer.sync.resume();
+      }
+    } else {
+      this.element.innerHTML = `
+        <span class="mw3-sync-progress__text">Initializing...</span>
+      `;
+    }
+  }
+
+  /**
+   * Inject default styles into document.
+   * Call once at app startup if not using custom CSS.
+   */
+  static injectStyles() {
+    if (document.getElementById('mw3-sync-progress-styles')) return;
+
+    const style = document.createElement('style');
+    style.id = 'mw3-sync-progress-styles';
+    style.textContent = `
+      .mw3-sync-progress {
+        position: relative;
+        height: 24px;
+        background: var(--mw3-sync-bg, #f0f0f0);
+        border-radius: 4px;
+        overflow: hidden;
+        font-family: system-ui, sans-serif;
+        font-size: 12px;
+      }
+
+      .mw3-sync-progress__bar {
+        position: absolute;
+        top: 0;
+        left: 0;
+        height: 100%;
+        background: var(--mw3-sync-bar, #4caf50);
+        transition: width 0.3s ease;
+      }
+
+      .mw3-sync-progress__text {
+        position: relative;
+        z-index: 1;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 100%;
+        color: var(--mw3-sync-text, #333);
+        padding: 0 8px;
+      }
+
+      .mw3-sync-progress--synced {
+        background: var(--mw3-sync-bar, #4caf50);
+      }
+
+      .mw3-sync-progress--synced .mw3-sync-progress__text {
+        color: white;
+      }
+
+      .mw3-sync-progress--error {
+        background: var(--mw3-sync-error, #f44336);
+      }
+
+      .mw3-sync-progress--error .mw3-sync-progress__text {
+        color: white;
+        justify-content: space-between;
+      }
+
+      .mw3-sync-progress__retry,
+      .mw3-sync-progress__resume {
+        background: rgba(255,255,255,0.2);
+        border: 1px solid rgba(255,255,255,0.4);
+        border-radius: 3px;
+        color: white;
+        padding: 2px 8px;
+        cursor: pointer;
+        font-size: 11px;
+      }
+
+      .mw3-sync-progress__retry:hover,
+      .mw3-sync-progress__resume:hover {
+        background: rgba(255,255,255,0.3);
+      }
+
+      .mw3-sync-progress--paused {
+        background: var(--mw3-sync-paused, #ff9800);
+      }
+
+      .mw3-sync-progress--paused .mw3-sync-progress__text {
+        color: white;
+        justify-content: space-between;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+}
+
+export default SyncProgressBar;
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/components/SyncProgressBar/SyncProgressBar.js
+git commit -m "feat(components): add SyncProgressBar UI component"
+```
+
+---
+
+## Task 13: Settings Modal with Indexer Storage Controls
+
+**Files:**
+- Create: `src/components/SettingsModal/SettingsModal.js`
+- Modify: `src/components/FloatingWalletButton/FloatingWalletButton.js`
+- Modify: `src/storage/index.js`
+
+**Step 1: Create IndexerSettings utility for localStorage preferences**
+
+```javascript
+// src/storage/IndexerSettings.js
+
+/**
+ * User preferences for EventIndexer storage.
+ * Persisted in localStorage.
+ */
+const STORAGE_KEY = 'mw3_indexer_settings';
+
+const IndexerSettings = {
+  /**
+   * Get all settings.
+   * @returns {Object}
+   */
+  get() {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      return stored ? JSON.parse(stored) : this.getDefaults();
+    } catch {
+      return this.getDefaults();
+    }
+  },
+
+  /**
+   * Get default settings.
+   * @returns {Object}
+   */
+  getDefaults() {
+    return {
+      storageEnabled: true,  // Allow IndexedDB storage
+      maxStorageMB: 50,      // Max storage in MB (0 = unlimited)
+    };
+  },
+
+  /**
+   * Update settings.
+   * @param {Object} updates - Partial settings to update
+   */
+  set(updates) {
+    const current = this.get();
+    const updated = { ...current, ...updates };
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(updated));
+    return updated;
+  },
+
+  /**
+   * Check if IndexedDB storage is enabled.
+   * @returns {boolean}
+   */
+  isStorageEnabled() {
+    return this.get().storageEnabled;
+  },
+
+  /**
+   * Clear all indexer data from IndexedDB.
+   * @returns {Promise<void>}
+   */
+  async clearAllData() {
+    // Find and delete all micro-web3 databases
+    if (typeof indexedDB === 'undefined') return;
+
+    const databases = await indexedDB.databases?.() || [];
+    const mw3Databases = databases.filter(db =>
+      db.name?.startsWith('micro-web3-events-') ||
+      db.name?.includes('colasseum-')
+    );
+
+    for (const db of mw3Databases) {
+      await new Promise((resolve, reject) => {
+        const request = indexedDB.deleteDatabase(db.name);
+        request.onsuccess = resolve;
+        request.onerror = reject;
+      });
+    }
+  },
+
+  /**
+   * Estimate current storage usage.
+   * @returns {Promise<{used: number, quota: number}>} Bytes
+   */
+  async getStorageEstimate() {
+    if (navigator.storage?.estimate) {
+      return navigator.storage.estimate();
+    }
+    return { used: 0, quota: 0 };
+  }
+};
+
+export default IndexerSettings;
+```
+
+**Step 2: Update storage/index.js to respect user settings**
+
+Modify the `selectAdapter` function in `src/storage/index.js`:
+
+```javascript
+// src/storage/index.js
+
+import StorageAdapter from './StorageAdapter.js';
+import IndexedDBAdapter from './IndexedDBAdapter.js';
+import MemoryAdapter from './MemoryAdapter.js';
+import IndexerSettings from './IndexerSettings.js';
+
+/**
+ * Select appropriate storage adapter based on config, environment, and user settings.
+ * @param {Object} config - Persistence configuration
+ * @returns {StorageAdapter}
+ */
+function selectAdapter(config) {
+  // Explicit memory mode in config
+  if (config?.type === 'memory') {
+    return new MemoryAdapter();
+  }
+
+  // Check user preference - if storage disabled, use memory
+  if (!IndexerSettings.isStorageEnabled()) {
+    console.log('[EventIndexer] User disabled IndexedDB storage, using memory');
+    return new MemoryAdapter();
+  }
+
+  // Check IndexedDB availability
+  if (typeof indexedDB !== 'undefined') {
+    return new IndexedDBAdapter();
+  }
+
+  // Fallback to memory
+  console.warn('[EventIndexer] IndexedDB not available, falling back to memory storage');
+  return new MemoryAdapter();
+}
+
+export {
+  StorageAdapter,
+  IndexedDBAdapter,
+  MemoryAdapter,
+  IndexerSettings,
+  selectAdapter
+};
+```
+
+**Step 3: Create SettingsModal component**
+
+```javascript
+// src/components/SettingsModal/SettingsModal.js
+
+import { IndexerSettings } from '../../storage/index.js';
+
+/**
+ * SettingsModal - Modal for user settings including indexer storage controls.
+ *
+ * @example
+ * const modal = new SettingsModal({ eventBus });
+ * modal.show();
+ */
+class SettingsModal {
+  constructor({ eventBus }) {
+    this.eventBus = eventBus;
+    this.element = null;
+    this.overlay = null;
+    this.isVisible = false;
+    this.state = {
+      storageEnabled: true,
+      storageUsed: 0,
+      storageQuota: 0,
+      clearing: false
+    };
+  }
+
+  async show() {
+    if (this.isVisible) return;
+
+    // Load current settings
+    const settings = IndexerSettings.get();
+    const estimate = await IndexerSettings.getStorageEstimate();
+
+    this.state = {
+      storageEnabled: settings.storageEnabled,
+      storageUsed: estimate.used || 0,
+      storageQuota: estimate.quota || 0,
+      clearing: false
+    };
+
+    this._createModal();
+    this.isVisible = true;
+  }
+
+  hide() {
+    if (!this.isVisible) return;
+
+    if (this.overlay && this.overlay.parentNode) {
+      this.overlay.parentNode.removeChild(this.overlay);
+    }
+    this.overlay = null;
+    this.element = null;
+    this.isVisible = false;
+  }
+
+  _createModal() {
+    // Inject styles if needed
+    SettingsModal.injectStyles();
+
+    // Create overlay
+    this.overlay = document.createElement('div');
+    this.overlay.className = 'mw3-settings-overlay';
+    this.overlay.addEventListener('click', (e) => {
+      if (e.target === this.overlay) this.hide();
+    });
+
+    // Create modal
+    this.element = document.createElement('div');
+    this.element.className = 'mw3-settings-modal';
+    this.element.innerHTML = this._render();
+
+    this.overlay.appendChild(this.element);
+    document.body.appendChild(this.overlay);
+
+    this._setupEventListeners();
+  }
+
+  _render() {
+    const { storageEnabled, storageUsed, storageQuota, clearing } = this.state;
+    const usedMB = (storageUsed / (1024 * 1024)).toFixed(1);
+    const quotaMB = (storageQuota / (1024 * 1024)).toFixed(0);
+
+    return `
+      <div class="mw3-settings-header">
+        <h2>Settings</h2>
+        <button class="mw3-settings-close" data-action="close">&times;</button>
+      </div>
+
+      <div class="mw3-settings-content">
+        <div class="mw3-settings-section">
+          <h3>Data Storage</h3>
+          <p class="mw3-settings-description">
+            Event data is cached locally to improve performance. You can disable this to save space.
+          </p>
+
+          <div class="mw3-settings-row">
+            <label class="mw3-settings-toggle">
+              <input type="checkbox" ${storageEnabled ? 'checked' : ''} data-setting="storageEnabled">
+              <span class="mw3-toggle-slider"></span>
+              <span class="mw3-toggle-label">Enable local event storage</span>
+            </label>
+          </div>
+
+          <div class="mw3-settings-info">
+            <span>Storage used: ${usedMB} MB${quotaMB > 0 ? ` / ${quotaMB} MB` : ''}</span>
+          </div>
+
+          <div class="mw3-settings-row">
+            <button class="mw3-settings-btn mw3-settings-btn--danger" data-action="clearData" ${clearing ? 'disabled' : ''}>
+              ${clearing ? 'Clearing...' : 'Clear All Cached Data'}
+            </button>
+          </div>
+
+          <p class="mw3-settings-note">
+            Disabling storage means event history will need to be re-fetched each session.
+          </p>
+        </div>
+      </div>
+
+      <div class="mw3-settings-footer">
+        <button class="mw3-settings-btn mw3-settings-btn--primary" data-action="close">Done</button>
+      </div>
+    `;
+  }
+
+  _setupEventListeners() {
+    // Close button
+    this.element.querySelectorAll('[data-action="close"]').forEach(btn => {
+      btn.addEventListener('click', () => this.hide());
+    });
+
+    // Storage toggle
+    const toggle = this.element.querySelector('[data-setting="storageEnabled"]');
+    if (toggle) {
+      toggle.addEventListener('change', (e) => {
+        const enabled = e.target.checked;
+        IndexerSettings.set({ storageEnabled: enabled });
+        this.state.storageEnabled = enabled;
+
+        // Emit event so indexer can react
+        this.eventBus.emit('settings:storageChanged', { enabled });
+      });
+    }
+
+    // Clear data button
+    const clearBtn = this.element.querySelector('[data-action="clearData"]');
+    if (clearBtn) {
+      clearBtn.addEventListener('click', async () => {
+        if (this.state.clearing) return;
+
+        this.state.clearing = true;
+        this._updateContent();
+
+        try {
+          await IndexerSettings.clearAllData();
+
+          // Update storage estimate
+          const estimate = await IndexerSettings.getStorageEstimate();
+          this.state.storageUsed = estimate.used || 0;
+          this.state.storageQuota = estimate.quota || 0;
+
+          // Emit event so indexer knows to resync
+          this.eventBus.emit('settings:dataCleared', {});
+        } catch (error) {
+          console.error('[SettingsModal] Failed to clear data:', error);
+        }
+
+        this.state.clearing = false;
+        this._updateContent();
+      });
+    }
+
+    // ESC key to close
+    this._escHandler = (e) => {
+      if (e.key === 'Escape') this.hide();
+    };
+    document.addEventListener('keydown', this._escHandler);
+  }
+
+  _updateContent() {
+    if (this.element) {
+      this.element.innerHTML = this._render();
+      this._setupEventListeners();
+    }
+  }
+
+  static injectStyles() {
+    if (document.getElementById('mw3-settings-styles')) return;
+
+    const style = document.createElement('style');
+    style.id = 'mw3-settings-styles';
+    style.textContent = `
+      .mw3-settings-overlay {
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background: rgba(0, 0, 0, 0.7);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 10000;
+        backdrop-filter: blur(4px);
+      }
+
+      .mw3-settings-modal {
+        background: linear-gradient(135deg, #1a1a2e, #16213e);
+        border: 1px solid rgba(218, 165, 32, 0.3);
+        border-radius: 12px;
+        width: 90%;
+        max-width: 400px;
+        color: #fff;
+        font-family: 'Lato', system-ui, sans-serif;
+        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.5);
+      }
+
+      .mw3-settings-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 1rem 1.25rem;
+        border-bottom: 1px solid rgba(218, 165, 32, 0.2);
+      }
+
+      .mw3-settings-header h2 {
+        margin: 0;
+        font-size: 1.125rem;
+        font-weight: 600;
+        color: rgba(218, 165, 32, 0.95);
+      }
+
+      .mw3-settings-close {
+        background: none;
+        border: none;
+        color: rgba(255, 255, 255, 0.6);
+        font-size: 1.5rem;
+        cursor: pointer;
+        padding: 0;
+        line-height: 1;
+      }
+
+      .mw3-settings-close:hover {
+        color: #fff;
+      }
+
+      .mw3-settings-content {
+        padding: 1.25rem;
+      }
+
+      .mw3-settings-section h3 {
+        margin: 0 0 0.5rem 0;
+        font-size: 0.9rem;
+        font-weight: 600;
+        color: rgba(255, 255, 255, 0.9);
+      }
+
+      .mw3-settings-description {
+        margin: 0 0 1rem 0;
+        font-size: 0.8rem;
+        color: rgba(255, 255, 255, 0.6);
+        line-height: 1.4;
+      }
+
+      .mw3-settings-row {
+        margin-bottom: 1rem;
+      }
+
+      .mw3-settings-toggle {
+        display: flex;
+        align-items: center;
+        gap: 0.75rem;
+        cursor: pointer;
+      }
+
+      .mw3-settings-toggle input {
+        display: none;
+      }
+
+      .mw3-toggle-slider {
+        width: 44px;
+        height: 24px;
+        background: rgba(255, 255, 255, 0.2);
+        border-radius: 12px;
+        position: relative;
+        transition: background 0.2s;
+      }
+
+      .mw3-toggle-slider::after {
+        content: '';
+        position: absolute;
+        top: 2px;
+        left: 2px;
+        width: 20px;
+        height: 20px;
+        background: #fff;
+        border-radius: 50%;
+        transition: transform 0.2s;
+      }
+
+      .mw3-settings-toggle input:checked + .mw3-toggle-slider {
+        background: rgba(218, 165, 32, 0.8);
+      }
+
+      .mw3-settings-toggle input:checked + .mw3-toggle-slider::after {
+        transform: translateX(20px);
+      }
+
+      .mw3-toggle-label {
+        font-size: 0.875rem;
+        color: rgba(255, 255, 255, 0.9);
+      }
+
+      .mw3-settings-info {
+        font-size: 0.75rem;
+        color: rgba(255, 255, 255, 0.5);
+        margin-bottom: 1rem;
+      }
+
+      .mw3-settings-note {
+        font-size: 0.75rem;
+        color: rgba(255, 255, 255, 0.4);
+        margin: 0;
+        font-style: italic;
+      }
+
+      .mw3-settings-btn {
+        padding: 0.625rem 1rem;
+        border-radius: 6px;
+        font-size: 0.875rem;
+        font-weight: 500;
+        cursor: pointer;
+        border: none;
+        transition: all 0.2s;
+      }
+
+      .mw3-settings-btn--primary {
+        background: rgba(218, 165, 32, 0.9);
+        color: #1a1a2e;
+      }
+
+      .mw3-settings-btn--primary:hover {
+        background: rgba(218, 165, 32, 1);
+      }
+
+      .mw3-settings-btn--danger {
+        background: rgba(255, 99, 71, 0.2);
+        color: rgba(255, 99, 71, 0.9);
+        border: 1px solid rgba(255, 99, 71, 0.3);
+      }
+
+      .mw3-settings-btn--danger:hover {
+        background: rgba(255, 99, 71, 0.3);
+      }
+
+      .mw3-settings-btn:disabled {
+        opacity: 0.5;
+        cursor: not-allowed;
+      }
+
+      .mw3-settings-footer {
+        padding: 1rem 1.25rem;
+        border-top: 1px solid rgba(218, 165, 32, 0.2);
+        display: flex;
+        justify-content: flex-end;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+}
+
+export default SettingsModal;
+```
+
+**Step 4: Wire up FloatingWalletButton to open SettingsModal**
+
+Modify `src/components/FloatingWalletButton/FloatingWalletButton.js`:
+
+Add import at top:
+```javascript
+import SettingsModal from '../SettingsModal/SettingsModal.js';
+```
+
+Add to constructor after `this.walletModal = null;`:
+```javascript
+this.settingsModal = null;
+```
+
+Modify the settings action handler in `setupDOMEventListeners()`:
+```javascript
+} else if (action === 'settings') {
+    this.setState({ menuOpen: false });
+    this.openSettings();
+}
+```
+
+Add new method:
+```javascript
+openSettings() {
+    if (!this.settingsModal) {
+        this.settingsModal = new SettingsModal({ eventBus: eventBus });
+    }
+    this.settingsModal.show();
+}
+```
+
+Add cleanup in `onUnmount()`:
+```javascript
+if (this.settingsModal) {
+    this.settingsModal.hide();
+    this.settingsModal = null;
+}
+```
+
+**Step 5: Commit**
+
+```bash
+git add src/storage/IndexerSettings.js src/storage/index.js src/components/SettingsModal/SettingsModal.js src/components/FloatingWalletButton/FloatingWalletButton.js
+git commit -m "feat(settings): add SettingsModal with indexer storage controls"
+```
+
+---
+
+## Task 14: Modify BlockchainService
+
+**Files:**
+- Modify: `src/services/BlockchainService.js`
+
+**Step 1: Add methods to support EventIndexer**
+
+Add these methods to BlockchainService class (find appropriate location in the class):
+
+```javascript
+  // NEW: Get provider instance (for EventIndexer)
+  getProvider() {
+    return this.provider;
+  }
+
+  // NEW: Create contract instance (for EventIndexer)
+  getContract(address, abi) {
+    if (!this.provider) {
+      throw new Error('Provider not initialized');
+    }
+    return new ethers.Contract(address, abi, this.provider);
+  }
+
+  // NEW: Get current chain ID (for EventIndexer)
+  async getChainId() {
+    if (!this.provider) {
+      throw new Error('Provider not initialized');
+    }
+    const network = await this.provider.getNetwork();
+    return Number(network.chainId);
+  }
+
+  // NEW: Get block by number (for EventIndexer)
+  async getBlock(blockNumber) {
+    if (!this.provider) {
+      throw new Error('Provider not initialized');
+    }
+    return this.provider.getBlock(blockNumber);
+  }
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/services/BlockchainService.js
+git commit -m "feat(BlockchainService): add getProvider, getContract, getChainId, getBlock methods"
+```
+
+---
+
+## Task 15: Modify ContractCache
+
+**Files:**
+- Modify: `src/services/ContractCache.js`
+
+**Step 1: Add event-driven invalidation support**
+
+Add to ContractCache constructor (after existing initialization):
+
+```javascript
+    // NEW: Optional event-driven invalidation from EventIndexer
+    if (options.eventInvalidation) {
+      this.setupEventInvalidation(options.eventInvalidation);
+    }
+```
+
+Add this method to ContractCache class:
+
+```javascript
+  // NEW: Configure which events invalidate which cache patterns
+  setupEventInvalidation(config) {
+    // config: { 'Transfer': ['balance'], 'Approval': ['allowance'] }
+    this.eventBus.on('indexer:newEvents', ({ eventType }) => {
+      const patterns = config[eventType];
+      if (patterns && Array.isArray(patterns)) {
+        this.invalidateByPattern(...patterns);
+      }
+    });
+  }
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/services/ContractCache.js
+git commit -m "feat(ContractCache): add event-driven invalidation from EventIndexer"
+```
+
+---
+
+## Task 16: Update Main Exports
+
+**Files:**
+- Modify: `src/index.js`
+
+**Step 1: Add new exports**
+
+Update src/index.js to include new exports:
+
+```javascript
+// Services
+export { default as BlockchainService } from './services/BlockchainService.js';
+export { default as WalletService } from './services/WalletService.js';
+export { default as ContractCache } from './services/ContractCache.js';
+export { default as PriceService } from './services/PriceService.js';
+export { default as IpfsService } from './services/IpfsService.js';
+export { default as WETHService } from './services/WETHService.js';
+
+// NEW in v1.2.0: EventIndexer
+export { default as EventIndexer } from './services/EventIndexer.js';
+
+// NEW: Storage adapters and settings (for custom implementations)
+export { IndexedDBAdapter, MemoryAdapter, IndexerSettings } from './storage/index.js';
+
+// UI Components (existing)
+export { default as FloatingWalletButton } from './components/FloatingWalletButton/FloatingWalletButton.js';
+export { default as WalletButton } from './components/WalletButton/WalletButton.js';
+export { default as WalletModal } from './components/Wallet/WalletModal.js';
+export { default as IpfsImage } from './components/Ipfs/IpfsImage.js';
+export { default as SwapInterface } from './components/Swap/SwapInterface.js';
+export { default as SwapInputs } from './components/Swap/SwapInputs.js';
+export { default as SwapButton } from './components/Swap/SwapButton.js';
+export { default as TransactionOptions } from './components/Swap/TransactionOptions.js';
+export { default as ApprovalModal } from './components/Modal/ApprovalModal.js';
+export { default as BondingCurve } from './components/BondingCurve/BondingCurve.js';
+export { default as PriceDisplay } from './components/Display/PriceDisplay.js';
+export { default as BalanceDisplay } from './components/Display/BalanceDisplay.js';
+export { default as MessagePopup } from './components/Util/MessagePopup.js';
+
+// NEW in v1.2.0: Sync progress component and settings modal
+export { default as SyncProgressBar } from './components/SyncProgressBar/SyncProgressBar.js';
+export { default as SettingsModal } from './components/SettingsModal/SettingsModal.js';
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/index.js
+git commit -m "feat(exports): add EventIndexer, storage adapters, and SyncProgressBar exports"
+```
+
+---
+
+## Task 17: Version Bump
+
+**Files:**
+- Modify: `package.json`
+
+**Step 1: Update version to 1.2.0**
+
+Change version field in package.json:
+
+```json
+{
+  "name": "@monygroupcorp/micro-web3",
+  "version": "1.2.0",
+  ...
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add package.json
+git commit -m "chore: bump version to 1.2.0"
+```
+
+---
+
+## Task 18: Build and Verify
+
+**Step 1: Run build**
+
+```bash
+cd micro-web3 && npm run build
+```
+
+Expected: Build succeeds with no errors.
+
+**Step 2: Verify exports**
+
+```bash
+node -e "import('./dist/micro-web3.esm.js').then(m => console.log(Object.keys(m)))"
+```
+
+Expected: Should list all exports including `EventIndexer`, `SyncProgressBar`, `IndexedDBAdapter`, `MemoryAdapter`.
+
+**Step 3: Commit build artifacts (if tracked)**
+
+```bash
+git add dist/
+git commit -m "chore: build v1.2.0"
+```
+
+---
+
+## Summary of Files Created/Modified
+
+### New Files (15)
+- `src/storage/StorageAdapter.js` - Base class interface
+- `src/storage/MemoryAdapter.js` - In-memory implementation
+- `src/storage/IndexedDBAdapter.js` - IndexedDB implementation
+- `src/storage/IndexerSettings.js` - User preferences for storage
+- `src/storage/index.js` - Storage module exports
+- `src/indexer/QueryEngine.js` - Events API
+- `src/indexer/SyncEngine.js` - Sync management
+- `src/indexer/EntityResolver.js` - Entities API
+- `src/indexer/Patterns.js` - Patterns API
+- `src/indexer/index.js` - Indexer module exports
+- `src/services/EventIndexer.js` - Main service
+- `src/components/SyncProgressBar/SyncProgressBar.js` - Sync status UI
+- `src/components/SettingsModal/SettingsModal.js` - Settings UI with storage controls
+
+### Modified Files (5)
+- `src/services/BlockchainService.js` - Added getProvider, getContract, getChainId, getBlock
+- `src/services/ContractCache.js` - Added setupEventInvalidation
+- `src/components/FloatingWalletButton/FloatingWalletButton.js` - Wire up SettingsModal
+- `src/index.js` - Added new exports
+- `package.json` - Version bump to 1.2.0
+
+---
+
+## Tests (Deferred)
+
+Per your request, tests go last. When ready to add tests:
+
+1. Set up test infrastructure (Jest or Vitest)
+2. Add unit tests for storage adapters
+3. Add unit tests for query engine
+4. Add unit tests for entity resolver
+5. Add unit tests for patterns
+6. Add integration tests for full sync cycle
+7. Add mock provider tests
+
+---
+
+**Plan complete and saved to `docs/plans/2026-01-22-event-indexer.md`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?**