holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/src/contracts/event-listener.js

@@ -0,0 +1,539 @@
+/**
+ * @fileoverview Event listener for Sankey flow visualization.
+ * Listens to contract events and transforms them into Sankey diagram format for visualizing fund flows.
+ * @module contracts/event-listener
+ */
+
+/**
+ * Standard Sankey event types emitted by Holosphere contracts.
+ * @constant {Object}
+ */
+export const SANKEY_EVENTS = {
+  // Fund flow events
+  FundsReceived: 'FundsReceived',
+  FundsCascaded: 'FundsCascaded',
+  FundsAllocated: 'FundsAllocated',
+  FundsClaimed: 'FundsClaimed',
+  FundsTransferred: 'FundsTransferred',
+
+  // Distribution summary
+  DistributionCompleted: 'DistributionCompleted',
+
+  // Structure events
+  ChildContractCreated: 'ChildContractCreated',
+  HolonCreated: 'HolonCreated',
+
+  // Membership events
+  MemberAdded: 'MemberAdded',
+  MemberRemoved: 'MemberRemoved',
+
+  // Weight/Zone events
+  WeightChanged: 'WeightChanged',
+  ZoneAssigned: 'ZoneAssigned',
+  AppreciationGiven: 'AppreciationGiven',
+
+  // Configuration events
+  SplitConfigured: 'SplitConfigured',
+  ContractSplitConfigured: 'ContractSplitConfigured'
+};
+
+/**
+ * Tracks contract events and transforms them into Sankey diagram format.
+ * Maintains event history and provides real-time flow visualization data.
+ * @class
+ */
+export class EventListener {
+  /**
+   * Create a new EventListener instance.
+   * @param {ChainManager} chainManager - Chain manager instance
+   */
+  constructor(chainManager) {
+    this.chainManager = chainManager;
+    this.listeners = new Map();
+    this.eventHistory = [];
+    this.sankeyNodes = new Map(); // address/userId -> node data
+    this.sankeyLinks = [];        // {source, target, value, ...}
+  }
+
+  /**
+   * Start listening to all Sankey-relevant events on a contract.
+   * @param {string} contractAddress - Contract address
+   * @param {string} holonId - Human-readable holon identifier
+   * @param {Object} contract - Ethers.js contract instance
+   */
+  async listenToContract(contractAddress, holonId, contract) {
+    const eventFilters = [
+      'FundsReceived',
+      'FundsCascaded',
+      'FundsAllocated',
+      'FundsClaimed',
+      'FundsTransferred',
+      'DistributionCompleted',
+      'MemberAdded',
+      'WeightChanged',
+      'ZoneAssigned',
+      'AppreciationGiven'
+    ];
+
+    for (const eventName of eventFilters) {
+      try {
+        const filter = contract.filters[eventName]?.();
+        if (filter) {
+          contract.on(eventName, (...args) => {
+            this._handleEvent(eventName, args, contractAddress, holonId);
+          });
+        }
+      } catch (e) {
+        // Event not found on this contract, skip
+      }
+    }
+
+    this.listeners.set(contractAddress, { contract, holonId });
+  }
+
+  /**
+   * Stop listening to a specific contract.
+   * @param {string} contractAddress - Contract address
+   */
+  stopListening(contractAddress) {
+    const listener = this.listeners.get(contractAddress);
+    if (listener) {
+      listener.contract.removeAllListeners();
+      this.listeners.delete(contractAddress);
+    }
+  }
+
+  /**
+   * Stop all active listeners.
+   */
+  stopAll() {
+    for (const [address, listener] of this.listeners) {
+      listener.contract.removeAllListeners();
+    }
+    this.listeners.clear();
+  }
+
+  /**
+   * Handle incoming event and transform to Sankey data.
+   * @private
+   * @param {string} eventName - Event name
+   * @param {Array} args - Event arguments
+   * @param {string} contractAddress - Contract address
+   * @param {string} holonId - Holon identifier
+   */
+  _handleEvent(eventName, args, contractAddress, holonId) {
+    const event = args[args.length - 1]; // Last arg is the event object
+    const timestamp = Date.now();
+
+    const parsed = {
+      type: eventName,
+      contractAddress,
+      holonId,
+      timestamp,
+      blockNumber: event?.blockNumber,
+      transactionHash: event?.transactionHash,
+      data: this._parseEventData(eventName, args)
+    };
+
+    this.eventHistory.push(parsed);
+    this._updateSankeyData(parsed);
+
+    // Emit custom event for real-time updates
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent('sankey-event', { detail: parsed }));
+    }
+  }
+
+  /**
+   * Parse event data based on event type.
+   * @private
+   * @param {string} eventName - Event name
+   * @param {Array} args - Event arguments
+   * @returns {Object} Parsed event data
+   */
+  _parseEventData(eventName, args) {
+    switch (eventName) {
+      case 'FundsReceived':
+        return {
+          contractAddress: args[0],
+          sender: args[1],
+          tokenAddress: args[2],
+          amount: args[3]?.toString()
+        };
+
+      case 'FundsCascaded':
+        return {
+          fromContract: args[0],
+          toContract: args[1],
+          fromHolonId: args[2],
+          toHolonId: args[3],
+          tokenAddress: args[4],
+          amount: args[5]?.toString(),
+          splitType: args[6]
+        };
+
+      case 'FundsAllocated':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          userId: args[2],
+          tokenAddress: args[3],
+          amount: args[4]?.toString(),
+          distributionType: args[5]
+        };
+
+      case 'FundsClaimed':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          userId: args[2],
+          beneficiary: args[3],
+          tokenAddress: args[4],
+          amount: args[5]?.toString()
+        };
+
+      case 'FundsTransferred':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          userId: args[2],
+          recipient: args[3],
+          tokenAddress: args[4],
+          amount: args[5]?.toString()
+        };
+
+      case 'DistributionCompleted':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          tokenAddress: args[2],
+          totalAmount: args[3]?.toString(),
+          recipientCount: Number(args[4]),
+          cascadeCount: Number(args[5])
+        };
+
+      case 'MemberAdded':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          userId: args[2],
+          addedBy: args[3]
+        };
+
+      case 'WeightChanged':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          userId: args[2],
+          oldWeight: args[3]?.toString(),
+          newWeight: args[4]?.toString()
+        };
+
+      case 'ZoneAssigned':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          userId: args[2],
+          oldZone: args[3]?.toString(),
+          newZone: args[4]?.toString()
+        };
+
+      case 'AppreciationGiven':
+        return {
+          contractAddress: args[0],
+          holonId: args[1],
+          fromUserId: args[2],
+          toUserId: args[3],
+          amount: args[4]?.toString()
+        };
+
+      default:
+        return { raw: args.slice(0, -1) };
+    }
+  }
+
+  /**
+   * Update Sankey nodes and links based on event.
+   * @private
+   * @param {Object} event - Parsed event object
+   */
+  _updateSankeyData(event) {
+    const { type, data } = event;
+
+    switch (type) {
+      case 'FundsReceived':
+        // Add external source node
+        this._ensureNode(data.sender, 'external', 'External');
+        this._ensureNode(data.contractAddress, 'contract', event.holonId);
+        this.sankeyLinks.push({
+          source: data.sender,
+          target: data.contractAddress,
+          value: BigInt(data.amount),
+          token: data.tokenAddress,
+          type: 'external_inflow'
+        });
+        break;
+
+      case 'FundsCascaded':
+        this._ensureNode(data.fromContract, 'contract', data.fromHolonId);
+        this._ensureNode(data.toContract, 'contract', data.toHolonId);
+        this.sankeyLinks.push({
+          source: data.fromContract,
+          target: data.toContract,
+          value: BigInt(data.amount),
+          token: data.tokenAddress,
+          type: 'cascade',
+          splitType: data.splitType
+        });
+        break;
+
+      case 'FundsAllocated':
+        this._ensureNode(data.contractAddress, 'contract', data.holonId);
+        this._ensureNode(data.userId, 'user', data.userId);
+        this.sankeyLinks.push({
+          source: data.contractAddress,
+          target: data.userId,
+          value: BigInt(data.amount),
+          token: data.tokenAddress,
+          type: 'allocation',
+          distributionType: data.distributionType
+        });
+        break;
+
+      case 'FundsClaimed':
+      case 'FundsTransferred':
+        this._ensureNode(data.userId, 'user', data.userId);
+        this._ensureNode(data.beneficiary || data.recipient, 'wallet',
+          (data.beneficiary || data.recipient).slice(0, 8) + '...');
+        this.sankeyLinks.push({
+          source: data.userId,
+          target: data.beneficiary || data.recipient,
+          value: BigInt(data.amount),
+          token: data.tokenAddress,
+          type: type === 'FundsClaimed' ? 'claim' : 'transfer'
+        });
+        break;
+
+      case 'MemberAdded':
+        this._ensureNode(data.userId, 'user', data.userId);
+        break;
+    }
+  }
+
+  /**
+   * Ensure a node exists in the Sankey graph.
+   * @private
+   * @param {string} id - Node ID
+   * @param {string} type - Node type (external, contract, user, wallet)
+   * @param {string} label - Display label
+   */
+  _ensureNode(id, type, label) {
+    if (!this.sankeyNodes.has(id)) {
+      this.sankeyNodes.set(id, { id, type, label });
+    }
+  }
+
+  /**
+   * Get Sankey-compatible data for visualization.
+   * @param {Object} [options={}] - Filter options
+   * @param {string} [options.tokenAddress] - Filter by token address
+   * @param {number} [options.fromBlock] - Filter from block number
+   * @param {number} [options.toBlock] - Filter to block number
+   * @param {string} [options.minValue] - Minimum value to include
+   * @returns {Object} Sankey data with nodes and links arrays
+   */
+  getSankeyData(options = {}) {
+    const { tokenAddress, fromBlock, toBlock, minValue } = options;
+
+    let links = [...this.sankeyLinks];
+
+    // Filter by token
+    if (tokenAddress) {
+      links = links.filter(l => l.token === tokenAddress);
+    }
+
+    // Filter by minimum value
+    if (minValue) {
+      const minBigInt = BigInt(minValue);
+      links = links.filter(l => l.value >= minBigInt);
+    }
+
+    // Get unique node IDs from filtered links
+    const nodeIds = new Set();
+    links.forEach(l => {
+      nodeIds.add(l.source);
+      nodeIds.add(l.target);
+    });
+
+    // Convert nodes to array format
+    const nodeArray = [...nodeIds].map(id => {
+      const node = this.sankeyNodes.get(id) || { id, type: 'unknown', label: id };
+      return {
+        id: node.id,
+        name: node.label,
+        type: node.type
+      };
+    });
+
+    // Create node index for links
+    const nodeIndex = new Map();
+    nodeArray.forEach((n, i) => nodeIndex.set(n.id, i));
+
+    // Convert links to Sankey format with numeric indices
+    const sankeyLinks = links.map(l => ({
+      source: nodeIndex.get(l.source),
+      target: nodeIndex.get(l.target),
+      value: Number(l.value) / 1e18, // Convert from wei to ETH
+      type: l.type,
+      splitType: l.splitType,
+      distributionType: l.distributionType,
+      token: l.token
+    }));
+
+    return {
+      nodes: nodeArray,
+      links: sankeyLinks
+    };
+  }
+
+  /**
+   * Get aggregated flow summary statistics.
+   * @returns {Object} Summary with inflow/outflow totals and distribution breakdown
+   */
+  getFlowSummary() {
+    const summary = {
+      totalInflow: 0n,
+      totalOutflow: 0n,
+      byHolon: {},
+      byUser: {},
+      byDistributionType: {
+        appreciation: 0n,
+        equal: 0n,
+        zone: 0n,
+        percentage: 0n,
+        peer_appreciation: 0n
+      }
+    };
+
+    for (const link of this.sankeyLinks) {
+      if (link.type === 'external_inflow') {
+        summary.totalInflow += link.value;
+      }
+      if (link.type === 'claim' || link.type === 'transfer') {
+        summary.totalOutflow += link.value;
+      }
+      if (link.distributionType && summary.byDistributionType[link.distributionType] !== undefined) {
+        summary.byDistributionType[link.distributionType] += link.value;
+      }
+    }
+
+    // Convert BigInt to strings for JSON serialization
+    return {
+      totalInflow: summary.totalInflow.toString(),
+      totalOutflow: summary.totalOutflow.toString(),
+      totalInflowEth: Number(summary.totalInflow) / 1e18,
+      totalOutflowEth: Number(summary.totalOutflow) / 1e18,
+      byDistributionType: Object.fromEntries(
+        Object.entries(summary.byDistributionType).map(([k, v]) => [k, v.toString()])
+      )
+    };
+  }
+
+  /**
+   * Query historical events from blockchain.
+   * @param {Object} contract - Ethers.js contract instance
+   * @param {string} eventName - Event name to query
+   * @param {Object} [options={}] - Query options
+   * @param {number} [options.fromBlock=0] - Starting block number
+   * @param {number|string} [options.toBlock='latest'] - Ending block number
+   * @returns {Promise<Array>} Array of parsed events
+   */
+  async queryPastEvents(contract, eventName, options = {}) {
+    const { fromBlock = 0, toBlock = 'latest' } = options;
+
+    try {
+      const filter = contract.filters[eventName]?.();
+      if (!filter) return [];
+
+      const events = await contract.queryFilter(filter, fromBlock, toBlock);
+      return events.map(e => ({
+        type: eventName,
+        contractAddress: e.address,
+        blockNumber: e.blockNumber,
+        transactionHash: e.transactionHash,
+        data: this._parseEventData(eventName, e.args)
+      }));
+    } catch (e) {
+      console.error(`Error querying ${eventName}:`, e);
+      return [];
+    }
+  }
+
+  /**
+   * Build Sankey data from historical blockchain events.
+   * @param {Object} contract - Ethers.js contract instance
+   * @param {string} holonId - Holon identifier
+   * @param {Object} [options={}] - Query options (fromBlock, toBlock)
+   * @returns {Promise<Object>} Sankey data with nodes and links
+   */
+  async buildFromHistory(contract, holonId, options = {}) {
+    const eventTypes = [
+      'FundsReceived',
+      'FundsCascaded',
+      'FundsAllocated',
+      'FundsClaimed',
+      'FundsTransferred',
+      'MemberAdded'
+    ];
+
+    for (const eventName of eventTypes) {
+      const events = await this.queryPastEvents(contract, eventName, options);
+      for (const event of events) {
+        event.holonId = holonId;
+        this.eventHistory.push(event);
+        this._updateSankeyData(event);
+      }
+    }
+
+    return this.getSankeyData();
+  }
+
+  /**
+   * Clear all stored event data.
+   */
+  clear() {
+    this.eventHistory = [];
+    this.sankeyNodes.clear();
+    this.sankeyLinks = [];
+  }
+
+  /**
+   * Export data for persistence.
+   * @returns {Object} Serializable event data
+   */
+  export() {
+    return {
+      events: this.eventHistory,
+      nodes: Object.fromEntries(this.sankeyNodes),
+      links: this.sankeyLinks.map(l => ({
+        ...l,
+        value: l.value.toString()
+      }))
+    };
+  }
+
+  /**
+   * Import previously exported data.
+   * @param {Object} data - Previously exported data
+   */
+  import(data) {
+    this.eventHistory = data.events || [];
+    this.sankeyNodes = new Map(Object.entries(data.nodes || {}));
+    this.sankeyLinks = (data.links || []).map(l => ({
+      ...l,
+      value: BigInt(l.value)
+    }));
+  }
+}
+
+export default EventListener;