holosphere 2.0.0-alpha1 → 2.0.0-alpha11

package/src/contracts/operations.js

@@ -0,0 +1,687 @@
+/**
+ * @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;
+    this.chainManager = chainManager;
+    this.ethers = null;
+  }
+
+  /**
+   * Load ethers.js library dynamically.
+   * @private
+   * @returns {Promise<Object>} Ethers.js module
+   */
+  async _loadEthers() {
+    if (!this.ethers) {
+      this.ethers = await import('ethers');
+    }
+    return this.ethers;
+  }
+
+  // ========================================================================
+  //                         MEMBER MANAGEMENT
+  // ========================================================================
+
+  /**
+   * Add a single member to the contract.
+   * @param {string} userId - User identifier (string-based, e.g., 'alice', 'telegram_12345')
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   */
+  async addMember(userId) {
+    const tx = await this.contract.addMember(userId);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Add multiple members at once (batch operation).
+   * @param {string[]} userIds - Array of user identifiers
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   */
+  async addMembers(userIds) {
+    const tx = await this.contract.addMembers(userIds);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Get all member user IDs.
+   * @returns {Promise<string[]>} Array of user IDs
+   */
+  async getMembers() {
+    const userIds = await this.contract.userIds();
+    // userIds is typically a getter for the array - try different approaches
+    try {
+      // Try to get all members by iterating
+      const members = [];
+      let i = 0;
+      while (true) {
+        try {
+          const userId = await this.contract.userIds(i);
+          members.push(userId);
+          i++;
+        } catch {
+          break;
+        }
+      }
+      return members;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Check if a user is a member.
+   * @param {string} userId - User identifier
+   * @returns {Promise<boolean>} True if user is a member
+   */
+  async isMember(userId) {
+    try {
+      // Different contracts use different naming conventions
+      if (this.type === 'Splitter') {
+        return await this.contract.isSplitterMember(userId);
+      }
+      return await this.contract.isMember(userId);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 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)
+   */
+  async getUserAddress(userId) {
+    return this.contract.userIdToAddress(userId);
+  }
+
+  // ========================================================================
+  //                         FUND DISTRIBUTION
+  // ========================================================================
+
+  /**
+   * 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: string, receipt: Object}>} Transaction details
+   */
+  async reward(tokenAddress, amount) {
+    const ethers = await this._loadEthers();
+    const amountBigInt = typeof amount === 'string' ? ethers.parseUnits(amount, 18) : amount;
+    const tx = await this.contract.reward(tokenAddress, amountBigInt);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Trigger reward distribution for ETH.
+   * @param {string} amount - Amount in ETH (e.g., '1.5' for 1.5 ETH)
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   */
+  async rewardEth(amount) {
+    const ethers = await this._loadEthers();
+    const amountWei = ethers.parseEther(amount);
+    const tx = await this.contract.reward(
+      '0x0000000000000000000000000000000000000000',
+      amountWei,
+      { value: amountWei }
+    );
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Send ETH directly to contract (triggers receive/fallback).
+   * @param {string} amount - Amount in ETH
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   */
+  async sendEth(amount) {
+    const ethers = await this._loadEthers();
+    const signer = this.chainManager.getSigner();
+    const amountWei = ethers.parseEther(amount);
+    const tx = await signer.sendTransaction({
+      to: await this.contract.getAddress(),
+      value: amountWei
+    });
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Claim accumulated rewards for a user.
+   * @param {string} userId - User identifier
+   * @param {string} beneficiaryAddress - Ethereum address to receive funds
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   */
+  async claim(userId, beneficiaryAddress) {
+    const tx = await this.contract.claim(userId, beneficiaryAddress);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Get ETH balance for a user.
+   * @param {string} userId - User identifier
+   * @returns {Promise<string>} Balance in ETH as decimal string
+   */
+  async getEthBalance(userId) {
+    const ethers = await this._loadEthers();
+    const balance = await this.contract.etherBalance(userId);
+    return ethers.formatEther(balance);
+  }
+
+  /**
+   * 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) as decimal string
+   */
+  async getTokenBalance(userId, tokenAddress) {
+    const ethers = await this._loadEthers();
+    const balance = await this.contract.tokenBalance(userId, tokenAddress);
+    return ethers.formatUnits(balance, 18);
+  }
+
+  /**
+   * Check if user has already claimed rewards.
+   * @param {string} userId - User identifier
+   * @returns {Promise<boolean>} True if user has claimed
+   */
+  async hasClaimed(userId) {
+    return this.contract.hasClaimed(userId);
+  }
+
+  /**
+   * Get total deposited amount for a token.
+   * @param {string} tokenAddress - Token address (use zero address for ETH)
+   * @returns {Promise<string>} Total deposited as decimal string
+   */
+  async getTotalDeposited(tokenAddress) {
+    const ethers = await this._loadEthers();
+    const total = await this.contract.totalDeposited(tokenAddress);
+    return ethers.formatUnits(total, 18);
+  }
+
+  // ========================================================================
+  //                         SPLITTER OPERATIONS
+  // ========================================================================
+
+  /**
+   * 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: 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']);
+    if (internalPct + externalPct !== 100) {
+      throw new Error('Percentages must sum to 100');
+    }
+    const tx = await this.contract.setContractSplit(internalPct, externalPct);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * 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']);
+    const internal = await this.contract.internalContractSplitPercentage();
+    const external = await this.contract.externalContractSplitPercentage();
+    return {
+      internal: Number(internal),
+      external: Number(external)
+    };
+  }
+
+  /**
+   * Create a Managed child contract (Splitter only)
+   * @param {string} creatorUserId - Creator's user ID
+   * @param {string} name - Contract name
+   * @param {number} [parameter=0] - Optional parameter
+   * @returns {Promise<{address, txHash, receipt}>}
+   */
+  async createManagedContract(creatorUserId, name, parameter = 0) {
+    this._requireType(['Splitter']);
+    const tx = await this.contract.createManagedContract(creatorUserId, name, parameter);
+    const receipt = await tx.wait();
+    const address = await this.contract.contractsByType(`${name}_managed`);
+    return { address, txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Create a Zoned child contract (Splitter only)
+   * @param {string} creatorUserId - Creator's user ID
+   * @param {string} name - Contract name
+   * @param {number} [nZones=6] - Number of zones
+   * @returns {Promise<{address, txHash, receipt}>}
+   */
+  async createZonedContract(creatorUserId, name, nZones = 6) {
+    this._requireType(['Splitter']);
+    const tx = await this.contract.createZonedContract(creatorUserId, name, nZones);
+    const receipt = await tx.wait();
+    const address = await this.contract.contractsByType(`${name}_zoned`);
+    return { address, txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Get all child contract keys (Splitter only)
+   * @returns {Promise<string[]>}
+   */
+  async getChildContractKeys() {
+    this._requireType(['Splitter']);
+    return this.contract.getContractKeys();
+  }
+
+  /**
+   * Get child contract addresses (Splitter only)
+   * @returns {Promise<{keys: string[], addresses: string[]}>}
+   */
+  async getChildContracts() {
+    this._requireType(['Splitter']);
+    const [keys, addresses] = await this.contract.getContractAddresses();
+    return { keys, addresses };
+  }
+
+  /**
+   * Get child contract address by key (Splitter only)
+   * @param {string} key - Contract key (e.g., 'MyHolon_managed')
+   * @returns {Promise<string>}
+   */
+  async getChildContract(key) {
+    this._requireType(['Splitter']);
+    return this.contract.contractsByType(key);
+  }
+
+  // ========================================================================
+  //                     MANAGED OPERATIONS (Appreciation-Based)
+  // ========================================================================
+
+  /**
+   * Set appreciation values for members (Managed only)
+   * Appreciation determines reward distribution proportionally
+   * @param {string[]} userIds - Array of user identifiers
+   * @param {number[]} amounts - Array of appreciation amounts (integers)
+   * @returns {Promise<{txHash, receipt}>}
+   * @example
+   * // Alice gets 60%, Bob gets 40%
+   * await ops.setAppreciation(['alice', 'bob'], [300, 200]);
+   */
+  async setAppreciation(userIds, amounts) {
+    this._requireType(['Managed']);
+    if (userIds.length !== amounts.length) {
+      throw new Error('userIds and amounts arrays must have same length');
+    }
+    const tx = await this.contract.setAppreciation(userIds, amounts);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Get appreciation value for a user (Managed only)
+   * @param {string} userId - User identifier
+   * @returns {Promise<number>}
+   */
+  async getAppreciation(userId) {
+    this._requireType(['Managed']);
+    const appreciation = await this.contract.appreciation(userId);
+    return Number(appreciation);
+  }
+
+  /**
+   * Get total appreciation across all members (Managed only)
+   * @returns {Promise<number>}
+   */
+  async getTotalAppreciation() {
+    this._requireType(['Managed']);
+    const total = await this.contract.totalappreciation();
+    return Number(total);
+  }
+
+  // ========================================================================
+  //                     ZONED OPERATIONS (Tier-Based)
+  // ========================================================================
+
+  /**
+   * Add a user to a zone (Zoned only)
+   * Higher zones receive more rewards based on quadratic formula
+   * @param {string} senderUserId - Sender's user ID (for authorization)
+   * @param {string} userId - User to add to zone
+   * @param {number} zone - Zone number (0 = unassigned, 1-N = contribution tiers)
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async addToZone(senderUserId, userId, zone) {
+    this._requireType(['Zoned']);
+    const tx = await this.contract.addToZone(senderUserId, userId, zone);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Remove a user from their zone (Zoned only)
+   * @param {string} senderUserId - Sender's user ID
+   * @param {string} userId - User to remove
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async removeFromZone(senderUserId, userId) {
+    this._requireType(['Zoned']);
+    const tx = await this.contract.removeFromZone(senderUserId, userId);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Get a user's zone (Zoned only)
+   * @param {string} userId - User identifier
+   * @returns {Promise<number>}
+   */
+  async getZone(userId) {
+    this._requireType(['Zoned']);
+    const zone = await this.contract.zones(userId);
+    return Number(zone);
+  }
+
+  /**
+   * Get number of zones (Zoned only)
+   * @returns {Promise<number>}
+   */
+  async getNumZones() {
+    this._requireType(['Zoned']);
+    const nzones = await this.contract.nzones();
+    return Number(nzones);
+  }
+
+  /**
+   * Set the reward function parameters (Zoned only)
+   * Formula: reward_units = a*zone² + b*zone + c
+   * @param {string} senderUserId - Sender's user ID
+   * @param {number} a - Quadratic coefficient
+   * @param {number} b - Linear coefficient
+   * @param {number} c - Constant
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async setZoneParameters(senderUserId, a, b, c) {
+    this._requireType(['Zoned']);
+    const tx = await this.contract.setRewardFunction(senderUserId, a, b, c);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  // ========================================================================
+  //                 APPRECIATIVE OPERATIONS (Peer-to-Peer)
+  // ========================================================================
+
+  /**
+   * Give appreciation from one user to another (Appreciative only)
+   * Each member has a limited appreciation pool to distribute
+   * @param {string} fromUserId - Giver's user ID
+   * @param {string} toUserId - Receiver's user ID
+   * @param {number} amount - Amount of appreciation to give
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async appreciate(fromUserId, toUserId, amount) {
+    this._requireType(['Appreciative']);
+    const tx = await this.contract.appreciate(fromUserId, toUserId, amount);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Get appreciation given by a user (Appreciative only)
+   * @param {string} userId - User identifier
+   * @returns {Promise<number>}
+   */
+  async getAppreciationGiven(userId) {
+    this._requireType(['Appreciative']);
+    const given = await this.contract.appreciationGiven(userId);
+    return Number(given);
+  }
+
+  /**
+   * Get appreciation received by a user (Appreciative only)
+   * @param {string} userId - User identifier
+   * @returns {Promise<number>}
+   */
+  async getAppreciationReceived(userId) {
+    this._requireType(['Appreciative']);
+    const received = await this.contract.appreciationReceived(userId);
+    return Number(received);
+  }
+
+  /**
+   * Get remaining appreciation pool for a user (Appreciative only)
+   * @param {string} userId - User identifier
+   * @returns {Promise<number>}
+   */
+  async getAppreciationRemaining(userId) {
+    this._requireType(['Appreciative']);
+    const remaining = await this.contract.appreciationRemaining(userId);
+    return Number(remaining);
+  }
+
+  // ========================================================================
+  //                     BUNDLE OPERATIONS (2-Way Split)
+  // ========================================================================
+
+  /**
+   * Set steepness for zone decay (Bundle only)
+   * Higher steepness = faster decay = more concentration in higher zones
+   * @param {string|bigint} steepness - Steepness value (0 < s < 1e18, e.g., 0.5e18 for 50% decay)
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async setSteepness(steepness) {
+    this._requireType(['Bundle']);
+    const ethers = await this._loadEthers();
+    const steepnessValue = typeof steepness === 'string' ? ethers.parseEther(steepness) : steepness;
+    const tx = await this.contract.setSteepness(steepnessValue);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Get current steepness (Bundle only)
+   * @returns {Promise<string>} Steepness as decimal string (e.g., '0.5')
+   */
+  async getSteepness() {
+    this._requireType(['Bundle']);
+    const ethers = await this._loadEthers();
+    const steepness = await this.contract.steepness();
+    return ethers.formatEther(steepness);
+  }
+
+  /**
+   * Set interior split percentages (Bundle only)
+   * @param {string[]} userIds - User identifiers
+   * @param {number[]} percentages - Percentages (must sum to 100)
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async setInteriorSplit(userIds, percentages) {
+    this._requireType(['Bundle']);
+    const total = percentages.reduce((a, b) => a + b, 0);
+    if (total !== 100) {
+      throw new Error('Percentages must sum to 100');
+    }
+    const tx = await this.contract.setInteriorSplit(userIds, percentages);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  // ========================================================================
+  //                         GOVERNANCE (Bundle)
+  // ========================================================================
+
+  /**
+   * Start an election for new owner (Bundle only)
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async startElection() {
+    this._requireType(['Bundle']);
+    const tx = await this.contract.startElection();
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Nominate yourself as candidate (Bundle only)
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async nominateSelf() {
+    this._requireType(['Bundle']);
+    const tx = await this.contract.nominateSelf();
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Vote for a nominee (Bundle only)
+   * @param {string} nomineeAddress - Address of the nominee
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async vote(nomineeAddress) {
+    this._requireType(['Bundle']);
+    const tx = await this.contract.vote(nomineeAddress);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Finalize election and transfer ownership to winner (Bundle only)
+   * @returns {Promise<{txHash, receipt}>}
+   */
+  async finalizeElection() {
+    this._requireType(['Bundle']);
+    const tx = await this.contract.finalizeElection();
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+
+  // ========================================================================
+  //                         READ-ONLY QUERIES
+  // ========================================================================
+
+  /**
+   * Get contract name
+   * @returns {Promise<string>}
+   */
+  async getName() {
+    return this.contract.name();
+  }
+
+  /**
+   * Get contract owner address
+   * @returns {Promise<string>}
+   */
+  async getOwner() {
+    return this.contract.owner();
+  }
+
+  /**
+   * Get bot address (for Managed/Zoned)
+   * @returns {Promise<string>}
+   */
+  async getBotAddress() {
+    try {
+      return await this.contract.botAddress();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get creator user ID
+   * @returns {Promise<string>}
+   */
+  async getCreatorUserId() {
+    try {
+      return await this.contract.creatorUserId();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get contract address
+   * @returns {Promise<string>}
+   */
+  async getAddress() {
+    return this.contract.getAddress();
+  }
+
+  /**
+   * Get contract type
+   * @returns {string}
+   */
+  getType() {
+    return this.type;
+  }
+
+  // ========================================================================
+  //                            UTILITIES
+  // ========================================================================
+
+  /**
+   * 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)) {
+      throw new Error(`Operation only available for ${allowedTypes.join('/')} contracts. This is a ${this.type} contract.`);
+    }
+  }
+
+  /**
+   * Get raw contract instance for advanced usage.
+   * @returns {Object} Ethers.js Contract instance
+   */
+  getRawContract() {
+    return this.contract;
+  }
+
+  /**
+   * Execute a raw contract call.
+   * @param {string} method - Method name
+   * @param {...*} args - Method arguments
+   * @returns {Promise<*>} Method return value
+   */
+  async call(method, ...args) {
+    return this.contract[method](...args);
+  }
+
+  /**
+   * Execute a raw contract transaction.
+   * @param {string} method - Method name
+   * @param {...*} args - Method arguments
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   */
+  async send(method, ...args) {
+    const tx = await this.contract[method](...args);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash, receipt };
+  }
+}
+
+export default ContractOperations;