holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/contracts/event-listener.js

@@ -1,12 +1,12 @@
 /**
- * Event Listener for Sankey Flow Visualization
- *
- * Listens to contract events and transforms them into a format
- * suitable for Sankey diagram visualization of fund flows.
+ * @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 our contracts
+ * Standard Sankey event types emitted by Holosphere contracts.
+ * @constant {Object}
  */
 export const SANKEY_EVENTS = {
   // Fund flow events
@@ -38,9 +38,15 @@ export const SANKEY_EVENTS = {
 };
 
 /**
- * EventListener class for tracking contract events
+ * 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();
@@ -50,10 +56,10 @@ export class EventListener {
   }
 
   /**
-   * Start listening to all Sankey-relevant events on a contract
-   * @param {string} contractAddress - The contract address
+   * 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
+   * @param {Object} contract - Ethers.js contract instance
    */
   async listenToContract(contractAddress, holonId, contract) {
     const eventFilters = [
@@ -86,7 +92,8 @@ export class EventListener {
   }
 
   /**
-   * Stop listening to a contract
+   * Stop listening to a specific contract.
+   * @param {string} contractAddress - Contract address
    */
   stopListening(contractAddress) {
     const listener = this.listeners.get(contractAddress);
@@ -97,7 +104,7 @@ export class EventListener {
   }
 
   /**
-   * Stop all listeners
+   * Stop all active listeners.
    */
   stopAll() {
     for (const [address, listener] of this.listeners) {
@@ -107,7 +114,12 @@ export class EventListener {
   }
 
   /**
-   * Handle incoming event and transform to Sankey data
+   * 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
@@ -133,7 +145,11 @@ export class EventListener {
   }
 
   /**
-   * Parse event data based on event type
+   * 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) {
@@ -237,7 +253,9 @@ export class EventListener {
   }
 
   /**
-   * Update Sankey nodes and links based on event
+   * Update Sankey nodes and links based on event.
+   * @private
+   * @param {Object} event - Parsed event object
    */
   _updateSankeyData(event) {
     const { type, data } = event;
@@ -303,7 +321,11 @@ export class EventListener {
   }
 
   /**
-   * Ensure a node exists in the Sankey graph
+   * 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)) {
@@ -312,9 +334,13 @@ export class EventListener {
   }
 
   /**
-   * Get Sankey-compatible data for visualization
-   * @param {Object} options - Filter options
-   * @returns {Object} { nodes: [], links: [] }
+   * 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;
@@ -371,8 +397,8 @@ export class EventListener {
   }
 
   /**
-   * Get aggregated flow summary
-   * @returns {Object} Summary statistics
+   * Get aggregated flow summary statistics.
+   * @returns {Object} Summary with inflow/outflow totals and distribution breakdown
    */
   getFlowSummary() {
     const summary = {
@@ -414,10 +440,13 @@ export class EventListener {
   }
 
   /**
-   * Query historical events from blockchain
-   * @param {Object} contract - ethers.js contract instance
+   * Query historical events from blockchain.
+   * @param {Object} contract - Ethers.js contract instance
    * @param {string} eventName - Event name to query
-   * @param {Object} options - { fromBlock, toBlock }
+   * @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;
@@ -441,10 +470,11 @@ export class EventListener {
   }
 
   /**
-   * Build Sankey data from historical events
-   * @param {Object} contract - ethers.js contract instance
+   * Build Sankey data from historical blockchain events.
+   * @param {Object} contract - Ethers.js contract instance
    * @param {string} holonId - Holon identifier
-   * @param {Object} options - Query options
+   * @param {Object} [options={}] - Query options (fromBlock, toBlock)
+   * @returns {Promise<Object>} Sankey data with nodes and links
    */
   async buildFromHistory(contract, holonId, options = {}) {
     const eventTypes = [
@@ -469,7 +499,7 @@ export class EventListener {
   }
 
   /**
-   * Clear all stored data
+   * Clear all stored event data.
    */
   clear() {
     this.eventHistory = [];
@@ -478,7 +508,8 @@ export class EventListener {
   }
 
   /**
-   * Export data for persistence
+   * Export data for persistence.
+   * @returns {Object} Serializable event data
    */
   export() {
     return {
@@ -492,7 +523,8 @@ export class EventListener {
   }
 
   /**
-   * Import previously exported data
+   * Import previously exported data.
+   * @param {Object} data - Previously exported data
    */
   import(data) {
     this.eventHistory = data.events || [];

package/src/contracts/holon-contracts.js

@@ -1,12 +1,23 @@
 /**
- * HolonContracts - Per-holon contract management
- * Links holons to their smart contracts for fractal fund distribution
+ * @fileoverview Per-holon contract management for Holosphere.
+ * Links holons to their smart contracts for fractal fund distribution.
+ * @module contracts/holon-contracts
  */
 
 import { ContractDeployer, ABIs } from './deployer.js';
 import { ContractOperations } from './operations.js';
 
+/**
+ * Manages the mapping between holons and their deployed contracts.
+ * Provides deployment, linking, and retrieval operations.
+ * @class
+ */
 export class HolonContracts {
+  /**
+   * Create a new HolonContracts instance.
+   * @param {ChainManager} chainManager - Chain manager instance
+   * @param {ContractDeployer} [deployer] - Contract deployer instance (auto-created if not provided)
+   */
   constructor(chainManager, deployer) {
     this.chainManager = chainManager;
     this.deployer = deployer || new ContractDeployer(chainManager);
@@ -19,19 +30,20 @@ export class HolonContracts {
   }
 
   /**
-   * Set storage adapter for persisting holon-contract mappings
-   * @param {Object} storage - Storage adapter with get/set methods
+   * Set storage adapter for persisting holon-contract mappings.
+   * @param {Object} storage - Storage adapter with get/set/delete methods
    */
   setStorage(storage) {
     this.storage = storage;
   }
 
   /**
-   * Deploy a new contract for a holon
+   * Deploy a new contract for a holon.
    * @param {string} holonId - Holon identifier
    * @param {string} [type='Splitter'] - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
-   * @param {Object} [options] - Deployment options
-   * @returns {Promise<{contract, address, operations}>}
+   * @param {Object} [options={}] - Deployment options (varies by contract type)
+   * @returns {Promise<{contract: Object, address: string, operations: ContractOperations, txHash: string, type: string}>} Deployment details
+   * @throws {Error} If holon already has a contract
    */
   async deploy(holonId, type = 'Splitter', options = {}) {
     if (this.holonContracts.has(holonId)) {
@@ -106,11 +118,12 @@ export class HolonContracts {
   }
 
   /**
-   * Link a holon to an existing contract
+   * Link a holon to an existing deployed contract.
    * @param {string} holonId - Holon identifier
    * @param {string} contractAddress - Existing contract address
    * @param {string} [type='Splitter'] - Contract type
-   * @returns {Promise<{contract, address, operations}>}
+   * @returns {Promise<{contract: Object, address: string, operations: ContractOperations, type: string}>} Link details
+   * @throws {Error} If holon already has a contract or contract is invalid
    */
   async link(holonId, contractAddress, type = 'Splitter') {
     if (this.holonContracts.has(holonId)) {
@@ -159,9 +172,9 @@ export class HolonContracts {
   }
 
   /**
-   * Unlink a holon from its contract
+   * Unlink a holon from its contract.
    * @param {string} holonId - Holon identifier
-   * @returns {boolean} True if unlinked, false if no contract was linked
+   * @returns {Promise<boolean>} True if unlinked, false if no contract was linked
    */
   async unlink(holonId) {
     if (!this.holonContracts.has(holonId)) {
@@ -179,9 +192,9 @@ export class HolonContracts {
   }
 
   /**
-   * Get contract for a holon
+   * Get contract instance for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {Contract|null}
+   * @returns {Object|null} Ethers.js Contract instance or null if not found
    */
   getContract(holonId) {
     const data = this.holonContracts.get(holonId);
@@ -189,9 +202,9 @@ export class HolonContracts {
   }
 
   /**
-   * Get contract address for a holon
+   * Get contract address for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {string|null}
+   * @returns {string|null} Contract address or null if not found
    */
   getAddress(holonId) {
     const data = this.holonContracts.get(holonId);
@@ -199,9 +212,9 @@ export class HolonContracts {
   }
 
   /**
-   * Get operations wrapper for a holon
+   * Get operations wrapper for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {ContractOperations|null}
+   * @returns {ContractOperations|null} Operations wrapper or null if not found
    */
   getOperations(holonId) {
     const data = this.holonContracts.get(holonId);
@@ -209,9 +222,9 @@ export class HolonContracts {
   }
 
   /**
-   * Get contract type for a holon
+   * Get contract type for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {string|null}
+   * @returns {string|null} Contract type or null if not found
    */
   getType(holonId) {
     const data = this.holonContracts.get(holonId);
@@ -219,17 +232,17 @@ export class HolonContracts {
   }
 
   /**
-   * Check if a holon has a contract
+   * Check if a holon has a linked contract.
    * @param {string} holonId - Holon identifier
-   * @returns {boolean}
+   * @returns {boolean} True if holon has a contract
    */
   hasContract(holonId) {
     return this.holonContracts.has(holonId);
   }
 
   /**
-   * Get all holon-contract mappings
-   * @returns {Array<{holonId, address, type}>}
+   * Get all holon-contract mappings.
+   * @returns {Array<{holonId: string, address: string, type: string, deployedAt?: string, linkedAt?: string}>} Array of mappings
    */
   listAll() {
     const result = [];
@@ -246,9 +259,9 @@ export class HolonContracts {
   }
 
   /**
-   * Get holons by contract type
+   * Get holons by contract type.
    * @param {string} type - Contract type
-   * @returns {Array<{holonId, address}>}
+   * @returns {Array<{holonId: string, address: string}>} Array of holons with matching type
    */
   getByType(type) {
     const result = [];
@@ -264,8 +277,8 @@ export class HolonContracts {
   }
 
   /**
-   * Load holon-contract mappings from storage
-   * @returns {Promise<number>} Number of mappings loaded
+   * Load holon-contract mappings from storage.
+   * @returns {Promise<number>} Number of mappings successfully loaded
    */
   async loadFromStorage() {
     if (!this.storage) {
@@ -302,8 +315,10 @@ export class HolonContracts {
   }
 
   /**
-   * Save a holon-contract mapping to storage
+   * Save a holon-contract mapping to storage.
    * @private
+   * @param {string} holonId - Holon identifier
+   * @param {Object} data - Holon contract data
    */
   async _saveMapping(holonId, data) {
     if (!this.storage) return;
@@ -327,10 +342,10 @@ export class HolonContracts {
   }
 
   /**
-   * Get required holon operations (throws if not linked)
+   * Get required holon operations, throwing if not linked.
    * @param {string} holonId - Holon identifier
-   * @returns {ContractOperations}
-   * @throws {Error} If holon has no contract
+   * @returns {ContractOperations} Operations wrapper
+   * @throws {Error} If holon has no linked contract
    */
   requireOperations(holonId) {
     const ops = this.getOperations(holonId);

package/src/contracts/index.js

@@ -1,7 +1,6 @@
 /**
- * Holosphere Contracts Module
- * Smart contract integration for fractal fund distribution
- *
+ * @fileoverview Holosphere Contracts Module - Smart contract integration for fractal fund distribution.
+ * Provides a complete toolkit for deploying, managing, and interacting with Holosphere smart contracts.
  * @module contracts
  */
 
@@ -53,9 +52,9 @@ import { ContractQueries } from './queries.js';
 import { NETWORKS } from './networks.js';
 
 /**
- * Create a complete contracts module instance
- * @param {Object} [config] - Configuration options
- * @returns {Promise<Object>} Contracts module with all components
+ * Create a complete contracts module instance with all components initialized.
+ * @param {Object} [config={}] - Configuration options for ChainManager
+ * @returns {Promise<{chainManager: ChainManager, deployer: ContractDeployer, holonContracts: HolonContracts}>} Initialized contracts module
  */
 export async function createContractsModule(config = {}) {
   const chainManager = new ChainManager(config);

package/src/contracts/networks.js

@@ -1,8 +1,13 @@
 /**
- * Multi-chain network configurations for Holosphere contracts
- * Supports Ethereum, Polygon, Arbitrum, Base, Optimism and testnets
+ * @fileoverview Multi-chain network configurations for Holosphere contracts.
+ * Supports Ethereum, Polygon, Arbitrum, Base, Optimism, and their testnets.
+ * @module contracts/networks
  */
 
+/**
+ * Network configurations for all supported EVM chains.
+ * @constant {Object}
+ */
 export const NETWORKS = {
   // ========== MAINNETS ==========
   ethereum: {
@@ -152,9 +157,9 @@ export const NETWORKS = {
 };
 
 /**
- * Get network configuration by name or chain ID
- * @param {string|number} networkOrChainId - Network name or chain ID
- * @returns {Object|null} Network configuration or null if not found
+ * Get network configuration by name or chain ID.
+ * @param {string|number} networkOrChainId - Network name (e.g., 'sepolia') or chain ID (e.g., 11155111)
+ * @returns {Object|null} Network configuration object or null if not found
  */
 export function getNetwork(networkOrChainId) {
   if (typeof networkOrChainId === 'string') {
@@ -170,9 +175,9 @@ export function getNetwork(networkOrChainId) {
 }
 
 /**
- * Get all networks of a specific type
+ * Get all networks of a specific type.
  * @param {'mainnet'|'testnet'|'local'} type - Network type
- * @returns {Object} Networks of the specified type
+ * @returns {Object} Map of networks matching the specified type
  */
 export function getNetworksByType(type) {
   return Object.fromEntries(
@@ -181,7 +186,7 @@ export function getNetworksByType(type) {
 }
 
 /**
- * List all available network names
+ * List all available network names.
  * @returns {string[]} Array of network names
  */
 export function listNetworks() {
@@ -189,19 +194,19 @@ export function listNetworks() {
 }
 
 /**
- * Check if a network is supported
+ * Check if a network is supported.
  * @param {string} network - Network name
- * @returns {boolean}
+ * @returns {boolean} True if network is supported
  */
 export function isNetworkSupported(network) {
   return network in NETWORKS;
 }
 
 /**
- * Get explorer URL for a transaction
+ * Get block explorer URL for a transaction.
  * @param {string} network - Network name
  * @param {string} txHash - Transaction hash
- * @returns {string|null} Explorer URL or null
+ * @returns {string|null} Explorer URL or null if network has no explorer
  */
 export function getTxUrl(network, txHash) {
   const config = NETWORKS[network];
@@ -210,10 +215,10 @@ export function getTxUrl(network, txHash) {
 }
 
 /**
- * Get explorer URL for an address
+ * Get block explorer URL for an address.
  * @param {string} network - Network name
  * @param {string} address - Contract or wallet address
- * @returns {string|null} Explorer URL or null
+ * @returns {string|null} Explorer URL or null if network has no explorer
  */
 export function getAddressUrl(network, address) {
   const config = NETWORKS[network];