holosphere 2.0.0-alpha7 → 2.0.0-alpha9

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

package/src/contracts/operations.js

@@ -1,9 +1,21 @@
 /**
- * ContractOperations - All contract functions exposed with clear parameters
- * Provides a unified interface for interacting with all Holosphere contract types
+ * @fileoverview Unified operations interface for all Holosphere contract types.
+ * Provides a clean API for member management, fund distribution, and contract-specific operations.
+ * @module contracts/operations
  */
 
+/**
+ * Provides a unified interface for interacting with all Holosphere contract types.
+ * Wraps contract functions with clear parameters and type checking.
+ * @class
+ */
 export class ContractOperations {
+  /**
+   * Create a new ContractOperations instance.
+   * @param {Object} contract - Ethers.js Contract instance
+   * @param {string} type - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
+   * @param {ChainManager} chainManager - Chain manager instance
+   */
   constructor(contract, type, chainManager) {
     this.contract = contract;
     this.type = type;
@@ -12,8 +24,9 @@ export class ContractOperations {
   }
 
   /**
-   * Load ethers dynamically
+   * Load ethers.js library dynamically.
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
@@ -27,9 +40,9 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Add a single member to the contract
+   * Add a single member to the contract.
    * @param {string} userId - User identifier (string-based, e.g., 'alice', 'telegram_12345')
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async addMember(userId) {
     const tx = await this.contract.addMember(userId);
@@ -38,9 +51,9 @@ export class ContractOperations {
   }
 
   /**
-   * Add multiple members at once (batch operation)
+   * Add multiple members at once (batch operation).
    * @param {string[]} userIds - Array of user identifiers
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async addMembers(userIds) {
     const tx = await this.contract.addMembers(userIds);
@@ -49,8 +62,8 @@ export class ContractOperations {
   }
 
   /**
-   * Get all member user IDs
-   * @returns {Promise<string[]>}
+   * Get all member user IDs.
+   * @returns {Promise<string[]>} Array of user IDs
    */
   async getMembers() {
     const userIds = await this.contract.userIds();
@@ -75,9 +88,9 @@ export class ContractOperations {
   }
 
   /**
-   * Check if a user is a member
+   * Check if a user is a member.
    * @param {string} userId - User identifier
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} True if user is a member
    */
   async isMember(userId) {
     try {
@@ -92,7 +105,7 @@ export class ContractOperations {
   }
 
   /**
-   * Get the address associated with a user ID
+   * Get the Ethereum address associated with a user ID.
    * @param {string} userId - User identifier
    * @returns {Promise<string>} Ethereum address (or zero address if not set)
    */
@@ -105,10 +118,10 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Trigger reward distribution for ERC20 tokens
+   * Trigger reward distribution for ERC20 tokens.
    * @param {string} tokenAddress - ERC20 token contract address
    * @param {string|bigint} amount - Amount in wei (or token's smallest unit)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async reward(tokenAddress, amount) {
     const ethers = await this._loadEthers();
@@ -119,9 +132,9 @@ export class ContractOperations {
   }
 
   /**
-   * Trigger reward distribution for ETH
+   * Trigger reward distribution for ETH.
    * @param {string} amount - Amount in ETH (e.g., '1.5' for 1.5 ETH)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async rewardEth(amount) {
     const ethers = await this._loadEthers();
@@ -136,9 +149,9 @@ export class ContractOperations {
   }
 
   /**
-   * Send ETH directly to contract (triggers receive/fallback)
+   * Send ETH directly to contract (triggers receive/fallback).
    * @param {string} amount - Amount in ETH
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async sendEth(amount) {
     const ethers = await this._loadEthers();
@@ -153,10 +166,10 @@ export class ContractOperations {
   }
 
   /**
-   * Claim accumulated rewards for a user
+   * Claim accumulated rewards for a user.
    * @param {string} userId - User identifier
    * @param {string} beneficiaryAddress - Ethereum address to receive funds
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async claim(userId, beneficiaryAddress) {
     const tx = await this.contract.claim(userId, beneficiaryAddress);
@@ -165,9 +178,9 @@ export class ContractOperations {
   }
 
   /**
-   * Get ETH balance for a user
+   * Get ETH balance for a user.
    * @param {string} userId - User identifier
-   * @returns {Promise<string>} Balance in ETH
+   * @returns {Promise<string>} Balance in ETH as decimal string
    */
   async getEthBalance(userId) {
     const ethers = await this._loadEthers();
@@ -176,10 +189,10 @@ export class ContractOperations {
   }
 
   /**
-   * Get ERC20 token balance for a user
+   * Get ERC20 token balance for a user.
    * @param {string} userId - User identifier
    * @param {string} tokenAddress - ERC20 token address
-   * @returns {Promise<string>} Balance in tokens (18 decimals assumed)
+   * @returns {Promise<string>} Balance in tokens (18 decimals assumed) as decimal string
    */
   async getTokenBalance(userId, tokenAddress) {
     const ethers = await this._loadEthers();
@@ -188,18 +201,18 @@ export class ContractOperations {
   }
 
   /**
-   * Check if user has already claimed
+   * Check if user has already claimed rewards.
    * @param {string} userId - User identifier
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} True if user has claimed
    */
   async hasClaimed(userId) {
     return this.contract.hasClaimed(userId);
   }
 
   /**
-   * Get total deposited amount for a token
+   * Get total deposited amount for a token.
    * @param {string} tokenAddress - Token address (use zero address for ETH)
-   * @returns {Promise<string>}
+   * @returns {Promise<string>} Total deposited as decimal string
    */
   async getTotalDeposited(tokenAddress) {
     const ethers = await this._loadEthers();
@@ -212,10 +225,11 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Set the internal/external split percentages (Splitter only)
+   * Set the internal/external split percentages (Splitter only).
    * @param {number} internalPct - Internal percentage (0-100)
    * @param {number} externalPct - External percentage (0-100, must sum to 100 with internal)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   * @throws {Error} If percentages don't sum to 100 or not a Splitter contract
    */
   async setContractSplit(internalPct, externalPct) {
     this._requireType(['Splitter']);
@@ -228,8 +242,9 @@ export class ContractOperations {
   }
 
   /**
-   * Get current split percentages (Splitter only)
-   * @returns {Promise<{internal: number, external: number}>}
+   * Get current split percentages (Splitter only).
+   * @returns {Promise<{internal: number, external: number}>} Split percentages
+   * @throws {Error} If not a Splitter contract
    */
   async getContractSplit() {
     this._requireType(['Splitter']);
@@ -627,8 +642,10 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Require specific contract type(s)
+   * Require specific contract type(s).
    * @private
+   * @param {string[]} allowedTypes - Array of allowed contract types
+   * @throws {Error} If contract type doesn't match
    */
   _requireType(allowedTypes) {
     if (!allowedTypes.includes(this.type)) {
@@ -637,28 +654,28 @@ export class ContractOperations {
   }
 
   /**
-   * Get raw contract instance for advanced usage
-   * @returns {Contract}
+   * Get raw contract instance for advanced usage.
+   * @returns {Object} Ethers.js Contract instance
    */
   getRawContract() {
     return this.contract;
   }
 
   /**
-   * Execute a raw contract call
+   * Execute a raw contract call.
    * @param {string} method - Method name
-   * @param {Array} args - Method arguments
-   * @returns {Promise<any>}
+   * @param {...*} args - Method arguments
+   * @returns {Promise<*>} Method return value
    */
   async call(method, ...args) {
     return this.contract[method](...args);
   }
 
   /**
-   * Execute a raw contract transaction
+   * Execute a raw contract transaction.
    * @param {string} method - Method name
-   * @param {Array} args - Method arguments
-   * @returns {Promise<{txHash, receipt}>}
+   * @param {...*} args - Method arguments
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async send(method, ...args) {
     const tx = await this.contract[method](...args);

package/src/contracts/queries.js

@@ -1,43 +1,67 @@
 /**
- * Contract Query Utilities
- *
- * Utility kit for directly querying contract state:
- * zones, splits, appreciation, members, balances, etc.
+ * @fileoverview Contract query utilities for reading contract state.
+ * Provides read-only queries for zones, splits, appreciation, members, balances, and more.
+ * @module contracts/queries
  */
 
 import { ethers } from 'ethers';
-import { ContractABIs } from './index.js';
+// Import ABIs directly to avoid circular dependency with index.js
+import SplitterABI from './abis/Splitter.json' with { type: 'json' };
+import ManagedABI from './abis/Managed.json' with { type: 'json' };
+import ZonedABI from './abis/Zoned.json' with { type: 'json' };
+import AppreciativeABI from './abis/Appreciative.json' with { type: 'json' };
+import BundleABI from './abis/Bundle.json' with { type: 'json' };
+import HolonsABI from './abis/Holons.json' with { type: 'json' };
+
+const ContractABIs = {
+  Splitter: SplitterABI,
+  Managed: ManagedABI,
+  Zoned: ZonedABI,
+  Appreciative: AppreciativeABI,
+  Bundle: BundleABI,
+  Holons: HolonsABI
+};
 
 /**
- * Helper to format wei to ETH
+ * Helper to format wei to ETH.
+ * @private
+ * @param {bigint} wei - Wei amount
+ * @returns {string} ETH as decimal string
  */
 function formatEth(wei) {
   return ethers.formatEther(wei);
 }
 
 /**
- * Helper to format wei to ETH as number
+ * Helper to format wei to ETH as number.
+ * @private
+ * @param {bigint} wei - Wei amount
+ * @returns {number} ETH as number
  */
 function formatEthNumber(wei) {
   return Number(ethers.formatEther(wei));
 }
 
 /**
- * ContractQueries - Query utilities for all contract types
+ * Query utilities for all Holosphere contract types.
+ * Provides read-only access to contract state without requiring a signer.
+ * @class
  */
 export class ContractQueries {
   /**
-   * @param {ethers.Provider} provider - ethers.js provider
+   * Create a new ContractQueries instance.
+   * @param {Object} provider - Ethers.js provider instance
    */
   constructor(provider) {
     this.provider = provider;
   }
 
   /**
-   * Get a contract instance with the appropriate ABI
+   * Get a contract instance with the appropriate ABI.
    * @param {string} address - Contract address
-   * @param {string} flavor - Contract flavor (Splitter, Managed, Zoned, Appreciative, Bundle)
-   * @returns {ethers.Contract}
+   * @param {string} flavor - Contract flavor (Splitter, Managed, Zoned, Appreciative, Bundle, Holons)
+   * @returns {Object} Ethers.js Contract instance
+   * @throws {Error} If unknown contract flavor
    */
   getContract(address, flavor) {
     const abi = ContractABIs[flavor];
@@ -48,9 +72,9 @@ export class ContractQueries {
   }
 
   /**
-   * Auto-detect contract flavor by calling flavor()
+   * Auto-detect contract flavor by calling flavor() method.
    * @param {string} address - Contract address
-   * @returns {Promise<string>} Contract flavor
+   * @returns {Promise<string>} Contract flavor or 'Unknown'
    */
   async detectFlavor(address) {
     // Try with a minimal ABI that has flavor()
@@ -69,7 +93,10 @@ export class ContractQueries {
   // ==================== COMMON QUERIES ====================
 
   /**
-   * Get basic contract info
+   * Get basic contract information.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @returns {Promise<{address: string, name: string, flavor: string, version: string, creator: string, memberCount: number}>} Contract info
    */
   async getContractInfo(address, flavor) {
     const contract = this.getContract(address, flavor);
@@ -92,7 +119,10 @@ export class ContractQueries {
   }
 
   /**
-   * Get all members (userIds)
+   * Get all member user IDs.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @returns {Promise<string[]>} Array of user IDs
    */
   async getMembers(address, flavor) {
     const contract = this.getContract(address, flavor);
@@ -106,7 +136,11 @@ export class ContractQueries {
   }
 
   /**
-   * Get user's ETH balance
+   * Get user's ETH balance in the contract.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @returns {Promise<{wei: string, eth: number}>} Balance in wei and ETH
    */
   async getUserEthBalance(address, flavor, userId) {
     const contract = this.getContract(address, flavor);
@@ -118,7 +152,12 @@ export class ContractQueries {
   }
 
   /**
-   * Get user's token balance
+   * Get user's ERC20 token balance in the contract.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @param {string} tokenAddress - ERC20 token address
+   * @returns {Promise<{wei: string, formatted: number}>} Token balance
    */
   async getUserTokenBalance(address, flavor, userId, tokenAddress) {
     const contract = this.getContract(address, flavor);
@@ -130,7 +169,11 @@ export class ContractQueries {
   }
 
   /**
-   * Get total deposited for a token
+   * Get total deposited amount for a token.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} [tokenAddress] - Token address (defaults to ETH/zero address)
+   * @returns {Promise<{wei: string, formatted: number}>} Total deposited
    */
   async getTotalDeposited(address, flavor, tokenAddress) {
     const contract = this.getContract(address, flavor);
@@ -144,7 +187,11 @@ export class ContractQueries {
   }
 
   /**
-   * Check if user has claimed
+   * Check if user has claimed their rewards.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @returns {Promise<boolean>} True if claimed
    */
   async hasClaimed(address, flavor, userId) {
     const contract = this.getContract(address, flavor);
@@ -524,7 +571,9 @@ export class ContractQueries {
   // ==================== FULL SNAPSHOT ====================
 
   /**
-   * Get complete contract state snapshot
+   * Get complete contract state snapshot including all members and configuration.
+   * @param {string} address - Contract address
+   * @returns {Promise<Object>} Complete contract state
    */
   async getFullSnapshot(address) {
     const flavor = await this.detectFlavor(address);

package/src/core/holosphere.js

@@ -1,3 +1,14 @@
+/**
+ * @fileoverview Core HoloSphere class providing the foundational infrastructure
+ * for holonic geospatial communication.
+ *
+ * This module implements the core HoloSphere class that supports multiple storage
+ * backends (Nostr, GunDB, ActivityPub) and provides essential operations for
+ * distributed P2P communication and data management.
+ *
+ * @module core/holosphere
+ */
+
 import { createClient } from '../storage/nostr-client.js';
 import { BackendFactory } from '../storage/backend-factory.js';
 import * as gunWrapper from '../storage/gun-wrapper.js';
@@ -5,12 +16,16 @@ import * as gunFederation from '../storage/gun-federation.js';
 import { GunDBBackend } from '../storage/backends/gundb-backend.js';
 import pkg from '../../package.json' with { type: 'json' };
 
-// Gun will be loaded dynamically when needed
+/** @type {Function|null} Gun constructor, loaded dynamically */
 let Gun = null;
+/** @type {Promise<Function>|null} Promise for Gun loading */
 let gunLoadPromise = null;
 
 /**
- * Load Gun module dynamically
+ * Dynamically loads the Gun module.
+ * Uses lazy loading to reduce initial bundle size and improve startup time.
+ *
+ * @private
  * @returns {Promise<Function>} Gun constructor
  */
 async function loadGun() {
@@ -50,9 +65,20 @@ function getDefaultRelays() {
 }
 
 /**
- * HoloSphere - Holonic Geospatial Communication Infrastructure
- * Combines H3 hexagonal indexing with distributed P2P storage
- * Supports multiple storage backends: nostr, gundb, activitypub
+ * HoloSphere - Holonic Geospatial Communication Infrastructure.
+ *
+ * The core class that combines H3 hexagonal indexing with distributed P2P storage.
+ * Supports multiple storage backends including Nostr, GunDB, and ActivityPub.
+ *
+ * @class HoloSphere
+ * @example
+ * // Create with Nostr backend (default)
+ * const hs = new HoloSphere({ appName: 'myapp', relays: ['wss://relay.example.com'] });
+ *
+ * @example
+ * // Create with GunDB backend
+ * const hs = new HoloSphere({ appName: 'myapp', backend: 'gundb' });
+ * await hs.ready(); // Wait for async initialization
  */
 export class HoloSphere {
   /**
@@ -61,7 +87,7 @@ export class HoloSphere {
    * @param {string} config.backend - Storage backend: 'nostr' | 'gundb' | 'activitypub' (default: 'nostr')
    * @param {string[]} config.relays - Nostr relay URLs (default from HOLOSPHERE_RELAYS env or ['wss://relay.holons.io', 'wss://relay.nostr.band'])
    * @param {string} config.privateKey - Private key for signing (hex format, optional)
-   * @param {string} config.logLevel - Log verbosity: ERROR|WARN|INFO|DEBUG (default: 'WARN')
+   * @param {string} config.logLevel - Log verbosity: ERROR|WARN|INFO|DEBUG (default: 'INFO')
    * @param {boolean} config.hybridMode - Enable hybrid mode (local + relay queries) (default: true)
    * @param {Object} config.gundb - GunDB-specific configuration
    * @param {Object} config.activitypub - ActivityPub-specific configuration
@@ -97,7 +123,7 @@ export class HoloSphere {
       backend: config.backend || 'nostr',
       relays: config.relays || getDefaultRelays(),
       privateKey: config.privateKey || getEnv('HOLOSPHERE_PRIVATE_KEY'),
-      logLevel: config.logLevel || getEnv('HOLOSPHERE_LOG_LEVEL') || 'WARN',
+      logLevel: config.logLevel || getEnv('HOLOSPHERE_LOG_LEVEL') || 'INFO',
       hybridMode: config.hybridMode !== false, // Enable by default
     };
 
@@ -712,7 +738,10 @@ export class HoloSphere {
   // ============================================================================
 
   /**
-   * Close the backend and clean up resources
+   * Closes the backend and cleans up resources.
+   * Should be called when done using the HoloSphere instance.
+   *
+   * @returns {void}
    */
   close() {
     if (this._backend) {