holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/lib/contract-methods.js

@@ -1,6 +1,8 @@
 /**
- * Contract Methods Mixin
- * All blockchain contract operations for HoloSphere
+ * @fileoverview Blockchain contract methods mixin for HoloSphere.
+ * Provides comprehensive smart contract operations including deployment, member management,
+ * fund distribution, and governance features across multiple contract types.
+ * @module lib/contract-methods
  */
 
 import { ChainManager } from '../contracts/chain-manager.js';
@@ -9,16 +11,28 @@ import { HolonContracts } from '../contracts/holon-contracts.js';
 import * as networks from '../contracts/networks.js';
 
 /**
- * Mixin that adds contract methods to a HoloSphere class
+ * Mixin that adds blockchain contract methods to a HoloSphere class.
+ * Provides initialization, deployment, and interaction with Ethereum smart contracts
+ * including Splitter, Managed, Zoned, Appreciative, and Bundle contract types.
  * @param {Class} Base - Base class to extend
  * @returns {Class} Extended class with contract methods
  */
 export function withContractMethods(Base) {
   return class extends Base {
+    /**
+     * Check if contracts are initialized.
+     * @returns {boolean} True if contracts initialized
+     */
     hasContracts() {
       return this._contracts !== null;
     }
 
+    /**
+     * Ensure contracts are initialized, throw if not.
+     * @private
+     * @returns {Object} Contracts object
+     * @throws {Error} If contracts not initialized
+     */
     _requireContracts() {
       if (!this._contracts) {
         throw new Error('Contracts not initialized. Call initContracts() first.');
@@ -26,6 +40,14 @@ export function withContractMethods(Base) {
       return this._contracts;
     }
 
+    /**
+     * Initialize contracts with server-side configuration (Node.js).
+     * @param {Object} config - Contract configuration
+     * @param {string} config.network - Network name (mainnet, sepolia, hardhat, etc.)
+     * @param {string} config.privateKey - Private key for signing transactions
+     * @param {string} [config.rpcUrl] - Optional custom RPC URL
+     * @returns {Promise<Object>} Connection info with network details and address
+     */
     async initContracts(config) {
       const chainManager = new ChainManager(config);
       const connectionInfo = await chainManager.connect(
@@ -50,6 +72,11 @@ export function withContractMethods(Base) {
       };
     }
 
+    /**
+     * Initialize contracts with browser wallet (MetaMask, etc.).
+     * @param {string} network - Network name to connect to
+     * @returns {Promise<Object>} Connection info with network details
+     */
     async initContractsBrowser(network) {
       const chainManager = new ChainManager();
       const connectionInfo = await chainManager.connectBrowser(network);
@@ -67,56 +94,113 @@ export function withContractMethods(Base) {
       return connectionInfo;
     }
 
+    /**
+     * Deploy all core contracts (factory, templates, etc.).
+     * @param {Object} [options={}] - Deployment options
+     * @returns {Promise<Object>} Deployment result with addresses
+     */
     async deployContracts(options = {}) {
       const { deployer } = this._requireContracts();
       return deployer.deployAll(options);
     }
 
+    /**
+     * Load previously deployed contract addresses.
+     * @param {Object} addresses - Map of contract names to addresses
+     */
     loadDeployedContracts(addresses) {
       const { deployer } = this._requireContracts();
       deployer.loadDeployedAddresses(addresses);
     }
 
+    /**
+     * Get all deployed contract addresses.
+     * @returns {Object} Map of contract names to addresses
+     */
     getDeployedContracts() {
       const { deployer } = this._requireContracts();
       return deployer.getDeployedAddresses();
     }
 
+    /**
+     * Deploy a new contract for a holon.
+     * @param {string} holonId - Holon ID to deploy contract for
+     * @param {string} [type='Splitter'] - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
+     * @param {Object} [options={}] - Deployment options
+     * @returns {Promise<Object>} Deployment result with contract address
+     */
     async deployHolonContract(holonId, type = 'Splitter', options = {}) {
       const { holonContracts } = this._requireContracts();
       return holonContracts.deploy(holonId, type, options);
     }
 
+    /**
+     * Link an existing contract to a holon.
+     * @param {string} holonId - Holon ID to link
+     * @param {string} contractAddress - Contract address to link
+     * @param {string} [type='Splitter'] - Contract type
+     * @returns {Promise<void>}
+     */
     async linkHolonContract(holonId, contractAddress, type = 'Splitter') {
       const { holonContracts } = this._requireContracts();
       return holonContracts.link(holonId, contractAddress, type);
     }
 
+    /**
+     * Unlink contract from a holon.
+     * @param {string} holonId - Holon ID to unlink
+     * @returns {Promise<void>}
+     */
     async unlinkHolonContract(holonId) {
       const { holonContracts } = this._requireContracts();
       return holonContracts.unlink(holonId);
     }
 
+    /**
+     * Get contract instance for a holon.
+     * @param {string} holonId - Holon ID
+     * @returns {Object|null} Contract instance or null if not found
+     */
     getHolonContract(holonId) {
       if (!this._contracts) return null;
       return this._contracts.holonContracts.getContract(holonId);
     }
 
+    /**
+     * Get contract address for a holon.
+     * @param {string} holonId - Holon ID
+     * @returns {string|null} Contract address or null if not found
+     */
     getHolonContractAddress(holonId) {
       if (!this._contracts) return null;
       return this._contracts.holonContracts.getAddress(holonId);
     }
 
+    /**
+     * Check if holon has a linked contract.
+     * @param {string} holonId - Holon ID to check
+     * @returns {boolean} True if contract exists
+     */
     hasHolonContract(holonId) {
       if (!this._contracts) return false;
       return this._contracts.holonContracts.hasContract(holonId);
     }
 
+    /**
+     * List all holon contracts.
+     * @returns {Array<{holonId: string, address: string, type: string}>} Array of holon contract info
+     */
     listHolonContracts() {
       if (!this._contracts) return [];
       return this._contracts.holonContracts.listAll();
     }
 
+    /**
+     * Get operations interface for a holon contract.
+     * @param {string} holonId - Holon ID
+     * @returns {Object} Operations object with contract methods
+     * @throws {Error} If holon has no contract
+     */
     getHolonOperations(holonId) {
       const { holonContracts } = this._requireContracts();
       return holonContracts.requireOperations(holonId);
@@ -124,40 +208,97 @@ export function withContractMethods(Base) {
 
     // ========== MEMBER MANAGEMENT ==========
 
+    /**
+     * Add a member to holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to add
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractAddMember(holonId, userId) {
       return this.getHolonOperations(holonId).addMember(userId);
     }
 
+    /**
+     * Add multiple members to holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string[]} userIds - Array of user IDs to add
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractAddMembers(holonId, userIds) {
       return this.getHolonOperations(holonId).addMembers(userIds);
     }
 
+    /**
+     * Check if user is a member of holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to check
+     * @returns {Promise<boolean>} True if user is member
+     */
     async contractIsMember(holonId, userId) {
       return this.getHolonOperations(holonId).isMember(userId);
     }
 
     // ========== FUND DISTRIBUTION ==========
 
+    /**
+     * Distribute ERC20 token rewards to contract members.
+     * @param {string} holonId - Holon ID
+     * @param {string} tokenAddress - ERC20 token contract address
+     * @param {string|number} amount - Amount to distribute
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractReward(holonId, tokenAddress, amount) {
       return this.getHolonOperations(holonId).reward(tokenAddress, amount);
     }
 
+    /**
+     * Distribute ETH rewards to contract members.
+     * @param {string} holonId - Holon ID
+     * @param {string|number} amount - Amount of ETH to distribute (in wei)
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractRewardEth(holonId, amount) {
       return this.getHolonOperations(holonId).rewardEth(amount);
     }
 
+    /**
+     * Send ETH to holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string|number} amount - Amount of ETH to send (in wei)
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractSendEth(holonId, amount) {
       return this.getHolonOperations(holonId).sendEth(amount);
     }
 
+    /**
+     * Claim user's share of distributed funds.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID claiming funds
+     * @param {string} beneficiaryAddress - Address to send claimed funds to
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractClaim(holonId, userId, beneficiaryAddress) {
       return this.getHolonOperations(holonId).claim(userId, beneficiaryAddress);
     }
 
+    /**
+     * Get user's claimable ETH balance.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to check
+     * @returns {Promise<string>} ETH balance in wei
+     */
     async contractGetEthBalance(holonId, userId) {
       return this.getHolonOperations(holonId).getEthBalance(userId);
     }
 
+    /**
+     * Get user's claimable token balance.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to check
+     * @param {string} tokenAddress - Token contract address
+     * @returns {Promise<string>} Token balance
+     */
     async contractGetTokenBalance(holonId, userId, tokenAddress) {
       return this.getHolonOperations(holonId).getTokenBalance(userId, tokenAddress);
     }
@@ -280,10 +421,18 @@ export function withContractMethods(Base) {
       return this.getHolonOperations(holonId).getTotalDeposited(tokenAddress);
     }
 
+    /**
+     * Get network utility functions.
+     * @returns {Object} Network utilities module
+     */
     getNetworkUtils() {
       return networks;
     }
 
+    /**
+     * Get the chain manager instance.
+     * @returns {Object|null} ChainManager instance or null if not initialized
+     */
     getChainManager() {
       return this._contracts?.chainManager || null;
     }

package/src/lib/errors.js

@@ -1,18 +1,48 @@
 /**
- * HoloSphere Error Classes
+ * @fileoverview HoloSphere Custom Error Classes.
+ *
+ * Provides specialized error types for authorization and validation failures.
+ *
+ * @module lib/errors
  */
 
+/**
+ * Error thrown when an operation fails due to insufficient permissions.
+ *
+ * @class AuthorizationError
+ * @extends Error
+ */
 export class AuthorizationError extends Error {
+  /**
+   * Creates a new AuthorizationError.
+   *
+   * @param {string} message - Error message describing the authorization failure
+   * @param {string|null} [requiredPermission=null] - The permission that was required
+   */
   constructor(message, requiredPermission = null) {
     super(message);
+    /** @type {string} */
     this.name = 'AuthorizationError';
+    /** @type {string|null} */
     this.requiredPermission = requiredPermission;
   }
 }
 
+/**
+ * Error thrown when data validation fails.
+ *
+ * @class ValidationError
+ * @extends Error
+ */
 export class ValidationError extends Error {
+  /**
+   * Creates a new ValidationError.
+   *
+   * @param {string} message - Error message describing the validation failure
+   */
   constructor(message) {
     super(message);
+    /** @type {string} */
     this.name = 'ValidationError';
   }
 }

package/src/lib/federation-methods.js

@@ -1,6 +1,8 @@
 /**
- * Federation Methods Mixin
- * Cross-Holosphere federation and Nostr discovery operations
+ * @fileoverview Federation methods mixin for cross-HoloSphere federation and Nostr discovery.
+ * Provides federated data access, capability-based authorization, and federation request protocols
+ * for connecting multiple HoloSphere instances.
+ * @module lib/federation-methods
  */
 
 import * as registry from '../federation/registry.js';
@@ -14,7 +16,9 @@ import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex } from '@noble/hashes/utils';
 
 /**
- * Mixin that adds federation methods to a HoloSphere class
+ * Mixin that adds federation methods to a HoloSphere class.
+ * Enables cross-HoloSphere federation with capability-based access control,
+ * hologram creation, and Nostr-based discovery protocols.
  * @param {Class} Base - Base class to extend
  * @returns {Class} Extended class with federation methods
  */
@@ -22,6 +26,13 @@ export function withFederationMethods(Base) {
   return class extends Base {
     // === Cross-Holosphere Federation ===
 
+    /**
+     * Add a federated HoloSphere partner by public key.
+     * @param {string} pubKey - Public key (hex) of the federated HoloSphere
+     * @param {Object} [options={}] - Federation options (metadata, capabilities, etc.)
+     * @returns {Promise<Object>} Federation registration result
+     * @throws {ValidationError} If pubKey is invalid
+     */
     async addFederatedHolosphere(pubKey, options = {}) {
       if (!pubKey || typeof pubKey !== 'string') {
         throw new ValidationError('pubKey must be a valid public key string');
@@ -34,6 +45,11 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Remove a federated HoloSphere partner.
+     * @param {string} pubKey - Public key of the partner to remove
+     * @returns {Promise<void>}
+     */
     async removeFederatedHolosphere(pubKey) {
       return registry.removeFederatedPartner(
         this.client,
@@ -42,6 +58,10 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Get all federated HoloSphere public keys.
+     * @returns {Promise<string[]>} Array of federated public keys
+     */
     async getFederatedHolospheres() {
       return registry.getFederatedAuthors(
         this.client,
@@ -49,6 +69,10 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Get the complete federation registry.
+     * @returns {Promise<Object>} Federation registry with all partners and capabilities
+     */
     async getFederationRegistry() {
       return registry.getFederationRegistry(
         this.client,
@@ -56,6 +80,12 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Store an inbound capability token from a federated partner.
+     * @param {string} partnerPubKey - Partner's public key
+     * @param {Object} capabilityInfo - Capability token and metadata
+     * @returns {Promise<void>}
+     */
     async storeInboundCapability(partnerPubKey, capabilityInfo) {
       return registry.storeInboundCapability(
         this.client,
@@ -65,6 +95,15 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Read data from a federated source with capability verification.
+     * @param {string} sourcePubKey - Source HoloSphere public key
+     * @param {string} holonId - Holon ID to read from
+     * @param {string} lensName - Lens name to read from
+     * @param {string|null} [dataId=null] - Optional specific data ID (null for all)
+     * @returns {Promise<Object|Object[]>} Data from federated source
+     * @throws {AuthorizationError} If capability verification fails
+     */
     async readFromFederatedSource(sourcePubKey, holonId, lensName, dataId = null) {
       const capabilityEntry = await registry.getCapabilityForAuthor(
         this.client,
@@ -102,6 +141,19 @@ export function withFederationMethods(Base) {
       }
     }
 
+    /**
+     * Create a cross-HoloSphere hologram reference.
+     * Links data from another HoloSphere into this one using capability-based access.
+     * @param {string} sourcePubKey - Source HoloSphere public key
+     * @param {string} sourceHolon - Source holon ID
+     * @param {string} lensName - Lens name
+     * @param {string} dataId - Data ID
+     * @param {string} targetHolon - Target holon in this HoloSphere
+     * @param {Object} [options={}] - Hologram options
+     * @param {boolean} [options.embedCapability=true] - Embed capability in hologram
+     * @returns {Promise<Object>} Created hologram
+     * @throws {AuthorizationError} If no valid capability exists
+     */
     async createCrossHolosphereHologram(sourcePubKey, sourceHolon, lensName, dataId, targetHolon, options = {}) {
       const { embedCapability = true } = options;
 
@@ -134,6 +186,17 @@ export function withFederationMethods(Base) {
       return hologram;
     }
 
+    /**
+     * Issue a capability token for federated access.
+     * Grants another HoloSphere permission to access data with specified scope.
+     * @param {string} targetPubKey - Target HoloSphere public key to grant access to
+     * @param {Object} scope - Access scope (holonId, lensName, dataId patterns)
+     * @param {string[]} permissions - Array of permissions ('read', 'write', etc.)
+     * @param {Object} [options={}] - Capability options
+     * @param {number} [options.expiresIn=3600000] - Expiration time in milliseconds
+     * @param {boolean} [options.trackInRegistry=true] - Store in federation registry
+     * @returns {Promise<string>} Capability token
+     */
     async issueCapabilityForFederation(targetPubKey, scope, permissions, options = {}) {
       const { expiresIn = 3600000, trackInRegistry = true } = options;
 
@@ -179,6 +242,12 @@ export function withFederationMethods(Base) {
       return token;
     }
 
+    /**
+     * Hash a capability token for storage.
+     * @private
+     * @param {string} token - Capability token to hash
+     * @returns {Promise<string>} SHA256 hash of token
+     */
     async _hashToken(token) {
       const encoder = new TextEncoder();
       return bytesToHex(sha256(encoder.encode(token)));
@@ -186,6 +255,12 @@ export function withFederationMethods(Base) {
 
     // === Nostr Discovery Protocol ===
 
+    /**
+     * Send a federation request to another HoloSphere via Nostr.
+     * @param {string} targetPubKey - Target HoloSphere public key
+     * @param {Object} [options={}] - Request options (message, metadata, etc.)
+     * @returns {Promise<Object>} Request event
+     */
     async sendFederationRequest(targetPubKey, options = {}) {
       return discovery.sendFederationRequest(
         this.client,
@@ -195,10 +270,21 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Subscribe to incoming federation requests.
+     * @param {Function} callback - Callback function (request) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
     async subscribeFederationRequests(callback) {
       return discovery.subscribeFederationRequests(this.client, callback);
     }
 
+    /**
+     * Accept a federation request and establish partnership.
+     * @param {Object} request - Federation request object
+     * @param {Object} [options={}] - Acceptance options (capabilities to grant, etc.)
+     * @returns {Promise<Object>} Acceptance event
+     */
     async acceptFederationRequest(request, options = {}) {
       return discovery.acceptFederationRequest(
         this.client,
@@ -208,6 +294,12 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Decline a federation request.
+     * @param {Object} request - Federation request object
+     * @param {string} [reason=''] - Optional reason for declining
+     * @returns {Promise<Object>} Decline event
+     */
     async declineFederationRequest(request, reason = '') {
       return discovery.declineFederationRequest(
         this.client,
@@ -217,6 +309,11 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Subscribe to federation request acceptances.
+     * @param {Function} callback - Callback function (acceptance) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
     async subscribeFederationAcceptances(callback) {
       return discovery.subscribeFederationAcceptances(
         this.client,
@@ -225,10 +322,20 @@ export function withFederationMethods(Base) {
       );
     }
 
+    /**
+     * Subscribe to federation request declines.
+     * @param {Function} callback - Callback function (decline) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
     async subscribeFederationDeclines(callback) {
       return discovery.subscribeFederationDeclines(this.client, callback);
     }
 
+    /**
+     * Get all pending federation requests.
+     * @param {Object} [options={}] - Query options (limit, since, etc.)
+     * @returns {Promise<Object[]>} Array of pending requests
+     */
     async getPendingFederationRequests(options = {}) {
       return discovery.getPendingFederationRequests(this.client, options);
     }

package/src/lib/index.js

@@ -1,6 +1,7 @@
 /**
- * HoloSphere Library Modules
- * Mixins for extending the base HoloSphere class
+ * @fileoverview HoloSphere library modules and mixin composition utilities.
+ * Exports AI, contract, and federation method mixins for extending the base HoloSphere class.
+ * @module lib/index
  */
 
 export { withAIMethods } from './ai-methods.js';
@@ -9,10 +10,13 @@ export { withFederationMethods } from './federation-methods.js';
 export { AuthorizationError, ValidationError } from './errors.js';
 
 /**
- * Compose multiple mixins into a single class
+ * Compose multiple mixins into a single class.
+ * Applies mixins in order from left to right.
  * @param {Class} BaseClass - Base class to extend
- * @param {...Function} mixins - Mixin functions to apply
- * @returns {Class} Composed class
+ * @param {...Function} mixins - Mixin functions to apply sequentially
+ * @returns {Class} Composed class with all mixins applied
+ * @example
+ * const EnhancedClass = compose(BaseClass, withAIMethods, withContractMethods);
  */
 export function compose(BaseClass, ...mixins) {
   return mixins.reduce((acc, mixin) => mixin(acc), BaseClass);

package/src/schema/validator.js

@@ -1,17 +1,36 @@
 /**
- * JSON Schema Validation with Ajv and caching
+ * @fileoverview JSON Schema Validation with Ajv and caching.
+ *
+ * Provides JSON Schema validation using Ajv (Another JSON Schema Validator)
+ * with schema compilation caching for improved performance on repeated validations.
+ *
+ * @module schema/validator
  */
 
 import Ajv from 'ajv';
 
+/** @type {Ajv} Ajv instance configured for validation */
 const ajv = new Ajv({ allErrors: true, strict: false });
+
+/** @type {Map<string, {validator: Function, timestamp: number}>} Schema cache */
 const schemaCache = new Map();
-const CACHE_TTL = 3600000; // 1 hour in milliseconds
+
+/** @constant {number} Cache TTL in milliseconds (1 hour) */
+const CACHE_TTL = 3600000;
 
 /**
- * Validation Error class
+ * Custom error class for validation failures.
+ *
+ * @class ValidationError
+ * @extends Error
  */
 export class ValidationError extends Error {
+  /**
+   * Creates a new ValidationError.
+   *
+   * @param {string} message - Error message
+   * @param {Array} [errors=[]] - Array of Ajv error objects
+   */
   constructor(message, errors = []) {
     super(message);
     this.name = 'ValidationError';

package/src/spatial/h3-operations.js

@@ -1,3 +1,15 @@
+/**
+ * @fileoverview H3 Hexagonal Spatial Operations.
+ *
+ * Provides functions for working with H3 hexagonal hierarchical spatial indexing.
+ * H3 divides the world into hexagonal cells at 16 resolution levels (0-15),
+ * where resolution 0 covers the entire globe and resolution 15 provides
+ * approximately 0.5 square meter precision.
+ *
+ * @module spatial/h3-operations
+ * @see {@link https://h3geo.org/ H3 Spatial Indexing}
+ */
+
 import {
   latLngToCell,
   cellToParent,
@@ -7,7 +19,11 @@ import {
 } from 'h3-js';
 
 /**
- * Convert geographic coordinates to H3 holon ID
+ * Converts geographic coordinates to an H3 holon ID.
+ *
+ * @example
+ * // Get H3 cell for a location at resolution 9
+ * const holonId = toHolon(40.7128, -74.0060, 9); // New York City
  * @param {number} lat - Latitude (-90 to 90)
  * @param {number} lng - Longitude (-180 to 180)
  * @param {number} resolution - H3 resolution (0-15)

package/src/storage/backend-factory.js

@@ -1,8 +1,13 @@
 /**
- * Factory for creating storage backends
- * Supports lazy loading of backend implementations
+ * @fileoverview Factory for Creating Storage Backends.
+ *
+ * Provides a factory pattern for creating and managing storage backend instances.
+ * Supports lazy loading of backend implementations to reduce initial bundle size.
+ *
+ * @module storage/backend-factory
  */
 
+/** @type {Object<string, string>} Map of backend types to their module paths */
 const BACKEND_MODULES = {
   nostr: './backends/nostr-backend.js',
   gundb: './backends/gundb-backend.js',