holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/contracts/chain-manager.js

@@ -1,11 +1,21 @@
 /**
- * ChainManager - Multi-chain connection management for Holosphere contracts
- * Handles provider/signer setup, network switching, and wallet management
+ * @fileoverview Multi-chain connection manager for Holosphere smart contracts.
+ * Handles provider/signer setup, network switching, and wallet management across EVM chains.
+ * @module contracts/chain-manager
  */
 
 import { NETWORKS, getNetwork, isNetworkSupported } from './networks.js';
 
+/**
+ * Multi-chain connection manager for Holosphere contracts.
+ * Supports both RPC providers and browser wallets (MetaMask, etc.).
+ * @class
+ */
 export class ChainManager {
+  /**
+   * Create a new ChainManager instance.
+   * @param {Object} [config={}] - Configuration options
+   */
   constructor(config = {}) {
     this.config = config;
     this.provider = null;
@@ -17,8 +27,9 @@ export class ChainManager {
   }
 
   /**
-   * Initialize ethers.js (lazy load)
+   * Initialize ethers.js library (lazy load).
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
@@ -30,11 +41,12 @@ export class ChainManager {
   }
 
   /**
-   * Connect to a network
+   * Connect to a network using RPC provider.
    * @param {string} networkName - Network name (e.g., 'sepolia', 'polygon')
    * @param {string} [privateKey] - Private key for signing transactions
    * @param {string} [rpcUrl] - Custom RPC URL (overrides default)
-   * @returns {Promise<{provider, signer, network}>}
+   * @returns {Promise<{provider: Object, signer: Object|null, network: Object, networkName: string, config: Object}>} Connection details
+   * @throws {Error} If network is unsupported and no custom RPC URL provided
    */
   async connect(networkName, privateKey, rpcUrl) {
     const ethers = await this._loadEthers();
@@ -78,9 +90,10 @@ export class ChainManager {
   }
 
   /**
-   * Connect using browser wallet (MetaMask, etc.)
+   * Connect using browser wallet (MetaMask, etc.).
    * @param {string} [networkName] - Optionally switch to this network
-   * @returns {Promise<{provider, signer, network, address}>}
+   * @returns {Promise<{provider: Object, signer: Object, network: Object, address: string}>} Connection details including user address
+   * @throws {Error} If no browser wallet is detected
    */
   async connectBrowser(networkName) {
     const ethers = await this._loadEthers();
@@ -117,8 +130,11 @@ export class ChainManager {
   }
 
   /**
-   * Switch to a different network (browser wallet only)
+   * Switch to a different network (browser wallet only).
+   * Adds the network to the wallet if it doesn't exist.
    * @param {string} networkName - Target network name
+   * @returns {Promise<void>}
+   * @throws {Error} If not using a browser wallet or network is unknown
    */
   async switchNetwork(networkName) {
     if (typeof window === 'undefined' || !window.ethereum) {
@@ -165,8 +181,9 @@ export class ChainManager {
   }
 
   /**
-   * Get the current provider
-   * @returns {Provider}
+   * Get the current provider.
+   * @returns {Object} Ethers.js provider instance
+   * @throws {Error} If not initialized
    */
   getProvider() {
     this._requireInitialized();
@@ -174,8 +191,9 @@ export class ChainManager {
   }
 
   /**
-   * Get the current signer
-   * @returns {Signer}
+   * Get the current signer.
+   * @returns {Object} Ethers.js signer instance
+   * @throws {Error} If not initialized or no signer available
    */
   getSigner() {
     this._requireInitialized();
@@ -186,8 +204,9 @@ export class ChainManager {
   }
 
   /**
-   * Get the connected address
-   * @returns {Promise<string>}
+   * Get the connected wallet address.
+   * @returns {Promise<string>} Ethereum address
+   * @throws {Error} If no signer available
    */
   async getAddress() {
     const signer = this.getSigner();
@@ -195,9 +214,10 @@ export class ChainManager {
   }
 
   /**
-   * Get ETH balance of an address
+   * Get ETH balance of an address.
    * @param {string} [address] - Address to check (defaults to signer)
-   * @returns {Promise<string>} Balance in ETH
+   * @returns {Promise<string>} Balance in ETH as decimal string
+   * @throws {Error} If not initialized or no address/signer available
    */
   async getBalance(address) {
     this._requireInitialized();
@@ -211,8 +231,9 @@ export class ChainManager {
   }
 
   /**
-   * Get current network configuration
-   * @returns {Object}
+   * Get current network configuration.
+   * @returns {Object} Network configuration object
+   * @throws {Error} If not initialized
    */
   getNetworkConfig() {
     this._requireInitialized();
@@ -220,8 +241,9 @@ export class ChainManager {
   }
 
   /**
-   * Get current chain ID
-   * @returns {number}
+   * Get current chain ID.
+   * @returns {number} Chain ID as number
+   * @throws {Error} If not initialized
    */
   getChainId() {
     this._requireInitialized();
@@ -229,9 +251,9 @@ export class ChainManager {
   }
 
   /**
-   * Check if connected to the expected network
+   * Check if connected to the expected network.
    * @param {string} expectedNetwork - Expected network name
-   * @returns {boolean}
+   * @returns {boolean} True if on expected network
    */
   isOnNetwork(expectedNetwork) {
     if (!this._initialized) return false;
@@ -241,11 +263,12 @@ export class ChainManager {
   }
 
   /**
-   * Create a contract instance
+   * Create a contract instance.
    * @param {string} address - Contract address
    * @param {Array} abi - Contract ABI
    * @param {boolean} [useSigner=true] - Use signer for write operations
-   * @returns {Contract}
+   * @returns {Promise<Object>} Ethers.js Contract instance
+   * @throws {Error} If not initialized
    */
   async getContract(address, abi, useSigner = true) {
     this._requireInitialized();
@@ -255,11 +278,12 @@ export class ChainManager {
   }
 
   /**
-   * Deploy a contract
+   * Deploy a contract.
    * @param {Array} abi - Contract ABI
    * @param {string} bytecode - Contract bytecode
    * @param {Array} [constructorArgs=[]] - Constructor arguments
-   * @returns {Promise<{contract, address, deployTx}>}
+   * @returns {Promise<{contract: Object, address: string, deployTx: Object, txHash: string}>} Deployment details
+   * @throws {Error} If not initialized or no signer available
    */
   async deployContract(abi, bytecode, constructorArgs = []) {
     this._requireInitialized();
@@ -285,10 +309,11 @@ export class ChainManager {
   }
 
   /**
-   * Wait for a transaction to be mined
+   * Wait for a transaction to be mined.
    * @param {string} txHash - Transaction hash
    * @param {number} [confirmations=1] - Number of confirmations to wait for
-   * @returns {Promise<TransactionReceipt>}
+   * @returns {Promise<Object>} Transaction receipt
+   * @throws {Error} If not initialized
    */
   async waitForTransaction(txHash, confirmations = 1) {
     this._requireInitialized();
@@ -296,9 +321,10 @@ export class ChainManager {
   }
 
   /**
-   * Estimate gas for a transaction
+   * Estimate gas for a transaction.
    * @param {Object} tx - Transaction object
-   * @returns {Promise<bigint>}
+   * @returns {Promise<bigint>} Estimated gas amount
+   * @throws {Error} If not initialized
    */
   async estimateGas(tx) {
     this._requireInitialized();
@@ -306,8 +332,9 @@ export class ChainManager {
   }
 
   /**
-   * Get current gas price
-   * @returns {Promise<{gasPrice: string, maxFeePerGas: string, maxPriorityFeePerGas: string}>}
+   * Get current gas price and fee data.
+   * @returns {Promise<{gasPrice: string|null, maxFeePerGas: string|null, maxPriorityFeePerGas: string|null}>} Fee data in gwei
+   * @throws {Error} If not initialized
    */
   async getGasPrice() {
     this._requireInitialized();
@@ -321,10 +348,10 @@ export class ChainManager {
   }
 
   /**
-   * Parse units (e.g., ETH to wei)
+   * Parse units (e.g., ETH to wei).
    * @param {string|number} value - Value to parse
    * @param {string|number} [unit='ether'] - Unit name or decimals
-   * @returns {bigint}
+   * @returns {Promise<bigint>} Parsed value as bigint
    */
   async parseUnits(value, unit = 'ether') {
     const ethers = await this._loadEthers();
@@ -332,10 +359,10 @@ export class ChainManager {
   }
 
   /**
-   * Format units (e.g., wei to ETH)
+   * Format units (e.g., wei to ETH).
    * @param {bigint|string} value - Value to format
    * @param {string|number} [unit='ether'] - Unit name or decimals
-   * @returns {string}
+   * @returns {Promise<string>} Formatted value as decimal string
    */
   async formatUnits(value, unit = 'ether') {
     const ethers = await this._loadEthers();
@@ -343,8 +370,9 @@ export class ChainManager {
   }
 
   /**
-   * Check if manager is initialized
+   * Check if manager is initialized.
    * @private
+   * @throws {Error} If not initialized
    */
   _requireInitialized() {
     if (!this._initialized) {
@@ -353,15 +381,15 @@ export class ChainManager {
   }
 
   /**
-   * Check if connected
-   * @returns {boolean}
+   * Check if connected to a network.
+   * @returns {boolean} True if connected
    */
   isConnected() {
     return this._initialized && this.provider !== null;
   }
 
   /**
-   * Disconnect and clean up
+   * Disconnect and clean up resources.
    */
   disconnect() {
     this.provider = null;

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