holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/lib/contract-methods.js

@@ -0,0 +1,442 @@
+/**
+ * @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';
+import { ContractDeployer } from '../contracts/deployer.js';
+import { HolonContracts } from '../contracts/holon-contracts.js';
+import * as networks from '../contracts/networks.js';
+
+/**
+ * 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.');
+      }
+      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(
+        config.network,
+        config.privateKey,
+        config.rpcUrl
+      );
+
+      const deployer = new ContractDeployer(chainManager);
+      const holonContracts = new HolonContracts(chainManager, deployer);
+
+      this._contracts = {
+        chainManager,
+        deployer,
+        holonContracts,
+        network: config.network
+      };
+
+      return {
+        ...connectionInfo,
+        address: config.privateKey ? await chainManager.getAddress() : null
+      };
+    }
+
+    /**
+     * 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);
+
+      const deployer = new ContractDeployer(chainManager);
+      const holonContracts = new HolonContracts(chainManager, deployer);
+
+      this._contracts = {
+        chainManager,
+        deployer,
+        holonContracts,
+        network: chainManager.networkName
+      };
+
+      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);
+    }
+
+    // ========== 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);
+    }
+
+    // ========== SPLITTER OPERATIONS ==========
+
+    async contractSetSplit(holonId, internalPct, externalPct) {
+      return this.getHolonOperations(holonId).setContractSplit(internalPct, externalPct);
+    }
+
+    async contractGetSplit(holonId) {
+      return this.getHolonOperations(holonId).getContractSplit();
+    }
+
+    async contractCreateManaged(holonId, creatorUserId, name) {
+      return this.getHolonOperations(holonId).createManagedContract(creatorUserId, name);
+    }
+
+    async contractCreateZoned(holonId, creatorUserId, name, nZones = 6) {
+      return this.getHolonOperations(holonId).createZonedContract(creatorUserId, name, nZones);
+    }
+
+    async contractGetChildContracts(holonId) {
+      return this.getHolonOperations(holonId).getChildContracts();
+    }
+
+    // ========== MANAGED OPERATIONS ==========
+
+    async contractSetAppreciation(holonId, userIds, amounts) {
+      return this.getHolonOperations(holonId).setAppreciation(userIds, amounts);
+    }
+
+    async contractGetAppreciation(holonId, userId) {
+      return this.getHolonOperations(holonId).getAppreciation(userId);
+    }
+
+    async contractGetTotalAppreciation(holonId) {
+      return this.getHolonOperations(holonId).getTotalAppreciation();
+    }
+
+    // ========== ZONED OPERATIONS ==========
+
+    async contractAddToZone(holonId, senderUserId, userId, zone) {
+      return this.getHolonOperations(holonId).addToZone(senderUserId, userId, zone);
+    }
+
+    async contractRemoveFromZone(holonId, senderUserId, userId) {
+      return this.getHolonOperations(holonId).removeFromZone(senderUserId, userId);
+    }
+
+    async contractGetZone(holonId, userId) {
+      return this.getHolonOperations(holonId).getZone(userId);
+    }
+
+    async contractSetZoneParams(holonId, senderUserId, a, b, c) {
+      return this.getHolonOperations(holonId).setZoneParameters(senderUserId, a, b, c);
+    }
+
+    // ========== APPRECIATIVE OPERATIONS ==========
+
+    async contractAppreciate(holonId, fromUserId, toUserId, amount) {
+      return this.getHolonOperations(holonId).appreciate(fromUserId, toUserId, amount);
+    }
+
+    async contractGetAppreciationGiven(holonId, userId) {
+      return this.getHolonOperations(holonId).getAppreciationGiven(userId);
+    }
+
+    async contractGetAppreciationReceived(holonId, userId) {
+      return this.getHolonOperations(holonId).getAppreciationReceived(userId);
+    }
+
+    // ========== BUNDLE OPERATIONS ==========
+
+    async contractSetSteepness(holonId, steepness) {
+      return this.getHolonOperations(holonId).setSteepness(steepness);
+    }
+
+    async contractGetSteepness(holonId) {
+      return this.getHolonOperations(holonId).getSteepness();
+    }
+
+    async contractSetInteriorSplit(holonId, userIds, percentages) {
+      return this.getHolonOperations(holonId).setInteriorSplit(userIds, percentages);
+    }
+
+    // ========== GOVERNANCE ==========
+
+    async contractStartElection(holonId) {
+      return this.getHolonOperations(holonId).startElection();
+    }
+
+    async contractNominate(holonId) {
+      return this.getHolonOperations(holonId).nominateSelf();
+    }
+
+    async contractVote(holonId, nomineeAddress) {
+      return this.getHolonOperations(holonId).vote(nomineeAddress);
+    }
+
+    async contractFinalizeElection(holonId) {
+      return this.getHolonOperations(holonId).finalizeElection();
+    }
+
+    // ========== READ-ONLY QUERIES ==========
+
+    async contractGetName(holonId) {
+      return this.getHolonOperations(holonId).getName();
+    }
+
+    async contractGetOwner(holonId) {
+      return this.getHolonOperations(holonId).getOwner();
+    }
+
+    async contractGetBotAddress(holonId) {
+      return this.getHolonOperations(holonId).getBotAddress();
+    }
+
+    async contractGetTotalDeposited(holonId, tokenAddress) {
+      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;
+    }
+  };
+}
+
+export default withContractMethods;

package/src/lib/errors.js

@@ -0,0 +1,53 @@
+/**
+ * @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';
+  }
+}
+
+export default {
+  AuthorizationError,
+  ValidationError
+};