holosphere 2.0.0-alpha7 → 2.0.0-alpha9

package/src/contracts/deployer.js

@@ -1,6 +1,7 @@
 /**
- * ContractDeployer - 1-Click deployment for Holosphere smart contracts
- * Deploys all factories, registry, and individual holon contracts
+ * @fileoverview Contract deployment utilities for Holosphere smart contracts.
+ * Provides 1-click deployment for all factories, registry, and individual holon contracts.
+ * @module contracts/deployer
  */
 
 // Import ABIs
@@ -35,7 +36,16 @@ export const ABIs = {
   TestToken: TestTokenABI
 };
 
+/**
+ * Contract deployment manager for Holosphere contracts.
+ * Handles deployment of all contract types and factory infrastructure.
+ * @class
+ */
 export class ContractDeployer {
+  /**
+   * Create a new ContractDeployer instance.
+   * @param {ChainManager} chainManager - Chain manager instance
+   */
   constructor(chainManager) {
     this.chainManager = chainManager;
     this.deployedContracts = {};
@@ -43,8 +53,9 @@ export class ContractDeployer {
   }
 
   /**
-   * Load ethers from chain manager
+   * Load ethers.js library.
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
@@ -54,15 +65,15 @@ export class ContractDeployer {
   }
 
   /**
-   * 1-CLICK DEPLOY: Deploy entire Holosphere contract infrastructure
-   * Deploys: All factories + Holons registry + optional TestToken
-   *
-   * @param {Object} options - Deployment options
+   * 1-CLICK DEPLOY: Deploy entire Holosphere contract infrastructure.
+   * Deploys all factories, Holons registry, and optional TestToken.
+   * @param {Object} [options={}] - Deployment options
    * @param {string} [options.botAddress] - Bot address for managed operations (defaults to deployer)
    * @param {string} [options.testTokenSupply='1000000'] - Initial supply for test token (in whole tokens)
    * @param {boolean} [options.deployTestToken=true] - Whether to deploy test token
-   * @param {Function} [options.onProgress] - Callback for deployment progress
-   * @returns {Promise<Object>} Deployed contract addresses and instances
+   * @param {Function} [options.onProgress] - Callback for deployment progress updates
+   * @returns {Promise<Object>} Deployment details including contract addresses, explorer URLs, and metadata
+   * @throws {Error} If deployment fails
    */
   async deployAll(options = {}) {
     const ethers = await this._loadEthers();
@@ -190,12 +201,16 @@ export class ContractDeployer {
   }
 
   /**
-   * Deploy a Splitter contract for a holon (fractal ownership)
+   * Deploy a Splitter contract for fractal ownership distribution.
    * @param {string} holonId - Holon identifier
    * @param {string} name - Contract display name
    * @param {number} [splitPercentage=70] - Internal/External split (e.g., 70 = 70% internal, 30% external)
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.creatorUserId] - Creator user ID (defaults to holonId)
+   * @param {string} [options.managedFactory] - Managed factory address
+   * @param {string} [options.zonedFactory] - Zoned factory address
+   * @returns {Promise<{contract: Object, address: string, txHash: string, holonId: string, type: string, splitPercentage: number}>} Deployment details
+   * @throws {Error} If factories not deployed
    */
   async deploySplitter(holonId, name, splitPercentage = 70, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -231,10 +246,11 @@ export class ContractDeployer {
   }
 
   /**
-   * Deploy a Managed contract (appreciation-based distribution)
+   * Deploy a Managed contract for appreciation-based distribution.
    * @param {string} name - Contract name
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.botAddress] - Bot address for managing appreciation (defaults to deployer)
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string}>} Deployment details
    */
   async deployManaged(name, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -254,11 +270,13 @@ export class ContractDeployer {
   }
 
   /**
-   * Deploy a Zoned contract (tier-based distribution)
+   * Deploy a Zoned contract for tier-based distribution.
    * @param {string} name - Contract name
    * @param {number} [nZones=6] - Number of zones
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.botAddress] - Bot address for managing zones (defaults to deployer)
+   * @param {string} [options.creatorUserId] - Creator user ID (defaults to 'creator')
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, nZones: number}>} Deployment details
    */
   async deployZoned(name, nZones = 6, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -280,11 +298,11 @@ export class ContractDeployer {
   }
 
   /**
-   * Deploy an Appreciative contract (peer-to-peer appreciation)
+   * Deploy an Appreciative contract for peer-to-peer appreciation.
    * @param {string} name - Contract name
    * @param {string} creatorUserId - Creator's user ID
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string}>} Deployment details
    */
   async deployAppreciative(name, creatorUserId, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -303,13 +321,15 @@ export class ContractDeployer {
   }
 
   /**
-   * Deploy a Bundle contract (2-way split with steepness)
-   * This is the simplest way to deploy a holon - no registry needed!
+   * Deploy a Bundle contract for 2-way split with steepness-based zone decay.
+   * This is the simplest way to deploy a holon - no registry needed.
    * @param {string} name - Contract name
-   * @param {number} [steepness=500000000000000000n] - Steepness factor (0.5e18 = 50% decay)
+   * @param {bigint|string} [steepness] - Steepness factor (e.g., 0.5e18 = 50% decay, defaults to 0.5e18)
    * @param {number} [nZones=6] - Number of zones
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.creatorUserId] - Creator user ID (defaults to 'creator')
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, steepness: bigint, nZones: number, creatorUserId: string, name: string}>} Deployment details
+   * @throws {Error} If bytecode is not available
    */
   async deployBundle(name, steepness, nZones = 6, options = {}) {
     const ethers = await this._loadEthers();
@@ -345,12 +365,14 @@ export class ContractDeployer {
   }
 
   /**
-   * Deploy a Bundle contract directly (simplified 1-click deployment)
-   * No registry needed - just deploys and returns the address
+   * Deploy a Bundle contract directly (simplified 1-click deployment).
+   * No registry needed - just deploys and returns the address.
    * @param {string} holonId - Unique identifier for the holon
    * @param {string} name - Display name for the holon
-   * @param {Object} [options] - Options { steepness, nZones }
-   * @returns {Promise<{address, txHash, contract}>}
+   * @param {Object} [options={}] - Deployment options
+   * @param {bigint|string} [options.steepness] - Steepness factor
+   * @param {number} [options.nZones=6] - Number of zones
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, steepness: bigint, nZones: number, creatorUserId: string, name: string}>} Deployment details
    */
   async deployBundleDirect(holonId, name, options = {}) {
     const steepness = options.steepness;
@@ -363,9 +385,9 @@ export class ContractDeployer {
   }
 
   /**
-   * Deploy a TestToken (ERC20 for testing)
+   * Deploy a TestToken ERC20 for testing.
    * @param {string} [initialSupply='1000000'] - Initial supply in whole tokens
-   * @returns {Promise<{contract, address, txHash}>}
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, initialSupply: string}>} Deployment details
    */
   async deployTestToken(initialSupply = '1000000') {
     const ethers = await this._loadEthers();
@@ -385,11 +407,12 @@ export class ContractDeployer {
   }
 
   /**
-   * Create a holon bundle through the Holons registry
+   * Create a holon bundle through the Holons registry.
    * @param {string} creatorUserId - Creator's user ID
    * @param {string} name - Bundle name
    * @param {number} [parameter=70] - Split parameter
-   * @returns {Promise<{address, txHash}>}
+   * @returns {Promise<{address: string, txHash: string, name: string, creatorUserId: string}>} Created holon details
+   * @throws {Error} If Holons registry not deployed
    */
   async createHolonBundle(creatorUserId, name, parameter = 70) {
     if (!this.deployedContracts.holons) {
@@ -425,10 +448,11 @@ export class ContractDeployer {
   }
 
   /**
-   * Get contract instance by address
+   * Get contract instance by address and type.
    * @param {string} address - Contract address
-   * @param {string} type - Contract type (Splitter, Managed, Zoned, etc.)
-   * @returns {Promise<Contract>}
+   * @param {string} type - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle, Holons, TestToken)
+   * @returns {Promise<Object>} Ethers.js Contract instance
+   * @throws {Error} If unknown contract type
    */
   async getContract(address, type) {
     const abi = ABIs[type];
@@ -439,24 +463,28 @@ export class ContractDeployer {
   }
 
   /**
-   * Get deployed contract addresses
-   * @returns {Object}
+   * Get deployed contract addresses.
+   * @returns {Object} Map of contract names to addresses
    */
   getDeployedAddresses() {
     return { ...this.deployedContracts };
   }
 
   /**
-   * Load previously deployed contracts
-   * @param {Object} addresses - Contract addresses
+   * Load previously deployed contract addresses.
+   * @param {Object} addresses - Map of contract names to addresses
    */
   loadDeployedAddresses(addresses) {
     this.deployedContracts = { ...addresses };
   }
 
   /**
-   * Internal: Deploy a contract
+   * Internal helper to deploy a contract.
    * @private
+   * @param {Array} abi - Contract ABI
+   * @param {string} bytecode - Contract bytecode
+   * @param {Array} constructorArgs - Constructor arguments
+   * @returns {Promise<{contract: Object, address: string, txHash: string, explorerUrl: string|null}>} Deployment result
    */
   async _deployContract(abi, bytecode, constructorArgs) {
     const result = await this.chainManager.deployContract(abi, bytecode, constructorArgs);

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);