holosphere 2.0.0-alpha1 → 2.0.0-alpha11

package/src/contracts/queries.js

@@ -0,0 +1,638 @@
+/**
+ * @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 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.
+ * @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.
+ * @private
+ * @param {bigint} wei - Wei amount
+ * @returns {number} ETH as number
+ */
+function formatEthNumber(wei) {
+  return Number(ethers.formatEther(wei));
+}
+
+/**
+ * Query utilities for all Holosphere contract types.
+ * Provides read-only access to contract state without requiring a signer.
+ * @class
+ */
+export class ContractQueries {
+  /**
+   * 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.
+   * @param {string} address - Contract address
+   * @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];
+    if (!abi) {
+      throw new Error(`Unknown contract flavor: ${flavor}`);
+    }
+    return new ethers.Contract(address, abi, this.provider);
+  }
+
+  /**
+   * Auto-detect contract flavor by calling flavor() method.
+   * @param {string} address - Contract address
+   * @returns {Promise<string>} Contract flavor or 'Unknown'
+   */
+  async detectFlavor(address) {
+    // Try with a minimal ABI that has flavor()
+    const minAbi = [
+      'function flavor() view returns (string)',
+      'function version() view returns (string)'
+    ];
+    const contract = new ethers.Contract(address, minAbi, this.provider);
+    try {
+      return await contract.flavor();
+    } catch {
+      return 'Unknown';
+    }
+  }
+
+  // ==================== COMMON QUERIES ====================
+
+  /**
+   * 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);
+    const [name, contractFlavor, version, creator, size] = await Promise.all([
+      contract.name().catch(() => ''),
+      contract.flavor().catch(() => flavor),
+      contract.version().catch(() => ''),
+      contract.creator().catch(() => ethers.ZeroAddress),
+      contract.getSize().catch(() => 0n)
+    ]);
+
+    return {
+      address,
+      name,
+      flavor: contractFlavor,
+      version,
+      creator,
+      memberCount: Number(size)
+    };
+  }
+
+  /**
+   * 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);
+    const size = await contract.getSize();
+    const members = [];
+    for (let i = 0; i < size; i++) {
+      const userId = await contract.userIds(i);
+      members.push(userId);
+    }
+    return members;
+  }
+
+  /**
+   * 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);
+    const balance = await contract.etherBalance(userId);
+    return {
+      wei: balance.toString(),
+      eth: formatEthNumber(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);
+    const balance = await contract.tokenBalance(userId, tokenAddress);
+    return {
+      wei: balance.toString(),
+      formatted: formatEthNumber(balance)
+    };
+  }
+
+  /**
+   * 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);
+    // For ETH, use address(0)
+    const token = tokenAddress || ethers.ZeroAddress;
+    const total = await contract.totalDeposited(token);
+    return {
+      wei: total.toString(),
+      formatted: formatEthNumber(total)
+    };
+  }
+
+  /**
+   * 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);
+    return contract.hasClaimed(userId);
+  }
+
+  // ==================== SPLITTER QUERIES ====================
+
+  /**
+   * Get Splitter's internal/external split configuration
+   */
+  async getSplitterSplit(address) {
+    const contract = this.getContract(address, 'Splitter');
+    const [internal, external] = await Promise.all([
+      contract.internalContractSplitPercentage(),
+      contract.externalContractSplitPercentage()
+    ]);
+    return {
+      internalPercentage: Number(internal),
+      externalPercentage: Number(external),
+      internalPercent: Number(internal) / 100,
+      externalPercent: Number(external) / 100
+    };
+  }
+
+  /**
+   * Get Splitter's child contracts
+   */
+  async getSplitterChildren(address) {
+    const contract = this.getContract(address, 'Splitter');
+    const [keys, addresses] = await contract.getContractAddresses();
+    const children = [];
+    for (let i = 0; i < keys.length; i++) {
+      children.push({
+        key: keys[i],
+        address: addresses[i]
+      });
+    }
+    return children;
+  }
+
+  /**
+   * Get user's percentage split in Splitter
+   */
+  async getSplitterUserPercentage(address, userId) {
+    const contract = this.getContract(address, 'Splitter');
+    const pct = await contract.percentages(userId);
+    return {
+      basisPoints: Number(pct),
+      percent: Number(pct) / 100
+    };
+  }
+
+  /**
+   * Get all member percentages in Splitter
+   */
+  async getSplitterAllPercentages(address) {
+    const members = await this.getMembers(address, 'Splitter');
+    const contract = this.getContract(address, 'Splitter');
+    const results = [];
+    for (const userId of members) {
+      const pct = await contract.percentages(userId);
+      results.push({
+        userId,
+        basisPoints: Number(pct),
+        percent: Number(pct) / 100
+      });
+    }
+    return results;
+  }
+
+  // ==================== ZONED QUERIES ====================
+
+  /**
+   * Get Zoned contract configuration
+   */
+  async getZonedConfig(address) {
+    const contract = this.getContract(address, 'Zoned');
+    const [nzones, a, b, c] = await Promise.all([
+      contract.nzones(),
+      contract.a(),
+      contract.b(),
+      contract.c()
+    ]);
+    return {
+      numberOfZones: Number(nzones),
+      rewardFunction: {
+        a: Number(a),
+        b: Number(b),
+        c: Number(c)
+      }
+    };
+  }
+
+  /**
+   * Get user's zone assignment
+   */
+  async getUserZone(address, userId) {
+    const contract = this.getContract(address, 'Zoned');
+    const zone = await contract.zone(userId);
+    return Number(zone);
+  }
+
+  /**
+   * Get all members in a specific zone
+   */
+  async getZoneMembers(address, zoneNumber) {
+    const contract = this.getContract(address, 'Zoned');
+    return contract.getZoneMembers(zoneNumber);
+  }
+
+  /**
+   * Get complete zone breakdown
+   */
+  async getZonedBreakdown(address) {
+    const config = await this.getZonedConfig(address);
+    const contract = this.getContract(address, 'Zoned');
+    const zones = [];
+
+    for (let z = 1; z <= config.numberOfZones; z++) {
+      const members = await contract.getZoneMembers(z);
+      zones.push({
+        zone: z,
+        members,
+        memberCount: members.length
+      });
+    }
+
+    // Also get calculated rewards
+    const rewards = await contract.calculateRewards();
+    const rewardsByZone = rewards.map((r, i) => ({
+      zone: i + 1,
+      weight: Number(r)
+    }));
+
+    return {
+      config,
+      zones,
+      rewardWeights: rewardsByZone
+    };
+  }
+
+  // ==================== MANAGED QUERIES ====================
+
+  /**
+   * Get Managed contract appreciation info
+   */
+  async getManagedAppreciation(address, userId) {
+    const contract = this.getContract(address, 'Managed');
+    const appreciation = await contract.appreciation(userId);
+    const totalAppreciation = await contract.totalappreciation();
+    return {
+      userAppreciation: Number(appreciation),
+      totalAppreciation: Number(totalAppreciation),
+      sharePercent: Number(totalAppreciation) > 0
+        ? (Number(appreciation) / Number(totalAppreciation)) * 100
+        : 0
+    };
+  }
+
+  /**
+   * Get all member appreciation in Managed contract
+   */
+  async getManagedAllAppreciation(address) {
+    const members = await this.getMembers(address, 'Managed');
+    const contract = this.getContract(address, 'Managed');
+    const totalAppreciation = await contract.totalappreciation();
+    const maxAppreciation = await contract.maxAppreciation().catch(() => 0n);
+
+    const results = [];
+    for (const userId of members) {
+      const appreciation = await contract.appreciation(userId);
+      results.push({
+        userId,
+        appreciation: Number(appreciation),
+        sharePercent: Number(totalAppreciation) > 0
+          ? (Number(appreciation) / Number(totalAppreciation)) * 100
+          : 0
+      });
+    }
+
+    return {
+      members: results,
+      totalAppreciation: Number(totalAppreciation),
+      maxAppreciation: Number(maxAppreciation)
+    };
+  }
+
+  // ==================== APPRECIATIVE QUERIES ====================
+
+  /**
+   * Get Appreciative contract peer appreciation
+   */
+  async getAppreciativePeer(address, userId) {
+    const contract = this.getContract(address, 'Appreciative');
+    const [appreciation, remaining, totalAppreciation] = await Promise.all([
+      contract.appreciation(userId),
+      contract.remainingappreciation(userId),
+      contract.totalappreciation()
+    ]);
+    return {
+      received: Number(appreciation),
+      remainingToGive: Number(remaining),
+      totalPool: Number(totalAppreciation),
+      sharePercent: Number(totalAppreciation) > 0
+        ? (Number(appreciation) / Number(totalAppreciation)) * 100
+        : 0
+    };
+  }
+
+  /**
+   * Get all peer appreciation in Appreciative contract
+   */
+  async getAppreciativeAll(address) {
+    const members = await this.getMembers(address, 'Appreciative');
+    const contract = this.getContract(address, 'Appreciative');
+    const totalAppreciation = await contract.totalappreciation();
+
+    const results = [];
+    for (const userId of members) {
+      const [appreciation, remaining] = await Promise.all([
+        contract.appreciation(userId),
+        contract.remainingappreciation(userId)
+      ]);
+      results.push({
+        userId,
+        received: Number(appreciation),
+        remainingToGive: Number(remaining),
+        sharePercent: Number(totalAppreciation) > 0
+          ? (Number(appreciation) / Number(totalAppreciation)) * 100
+          : 0
+      });
+    }
+
+    return {
+      members: results,
+      totalAppreciation: Number(totalAppreciation)
+    };
+  }
+
+  // ==================== BUNDLE QUERIES ====================
+
+  /**
+   * Get Bundle contract configuration
+   */
+  async getBundleConfig(address) {
+    const contract = this.getContract(address, 'Bundle');
+    const [steepness, nzones, interiorPct, exteriorPct, electionActive] = await Promise.all([
+      contract.steepness(),
+      contract.nzones(),
+      contract.interiorPercentage(),
+      contract.exteriorPercentage(),
+      contract.electionActive()
+    ]);
+
+    return {
+      steepness: Number(steepness),
+      numberOfZones: Number(nzones),
+      interiorPercentage: Number(interiorPct) / 100, // Basis points to percent
+      exteriorPercentage: Number(exteriorPct) / 100,
+      electionActive
+    };
+  }
+
+  /**
+   * Get Bundle interior/exterior split
+   */
+  async getBundleSplit(address) {
+    const contract = this.getContract(address, 'Bundle');
+    const [interior, exterior] = await Promise.all([
+      contract.interiorPercentage(),
+      contract.exteriorPercentage()
+    ]);
+    return {
+      interiorBasisPoints: Number(interior),
+      exteriorBasisPoints: Number(exterior),
+      interiorPercent: Number(interior) / 100,
+      exteriorPercent: Number(exterior) / 100
+    };
+  }
+
+  /**
+   * Get Bundle zone weights
+   */
+  async getBundleZoneWeights(address) {
+    const contract = this.getContract(address, 'Bundle');
+    const weights = await contract.getZoneWeights();
+    return weights.map((w, i) => ({
+      zone: i + 1,
+      weight: Number(w)
+    }));
+  }
+
+  /**
+   * Get Bundle user's zone and interior share
+   */
+  async getBundleUserInfo(address, userId) {
+    const contract = this.getContract(address, 'Bundle');
+    const [zone, interiorShare, isInterior, isExterior, isMember] = await Promise.all([
+      contract.zone(userId),
+      contract.interiorShare(userId),
+      contract.isInteriorMember(userId),
+      contract.isExteriorMember(userId),
+      contract.isBundleMember(userId)
+    ]);
+    return {
+      zone: Number(zone),
+      interiorShareBasisPoints: Number(interiorShare),
+      interiorSharePercent: Number(interiorShare) / 100,
+      isInteriorMember: isInterior,
+      isExteriorMember: isExterior,
+      isMember
+    };
+  }
+
+  /**
+   * Get Bundle interior members
+   */
+  async getBundleInteriorMembers(address) {
+    const contract = this.getContract(address, 'Bundle');
+    return contract.getInteriorMembers();
+  }
+
+  /**
+   * Get Bundle zone breakdown (exterior)
+   */
+  async getBundleZoneBreakdown(address) {
+    const config = await this.getBundleConfig(address);
+    const contract = this.getContract(address, 'Bundle');
+    const zones = [];
+
+    for (let z = 1; z <= config.numberOfZones; z++) {
+      const members = await contract.getZoneMembers(z);
+      zones.push({
+        zone: z,
+        members,
+        memberCount: members.length
+      });
+    }
+
+    return {
+      config,
+      zones,
+      zoneWeights: await this.getBundleZoneWeights(address)
+    };
+  }
+
+  /**
+   * Get Bundle election info
+   */
+  async getBundleElection(address) {
+    const contract = this.getContract(address, 'Bundle');
+    const [electionActive, candidates] = await Promise.all([
+      contract.electionActive(),
+      contract.getCandidates()
+    ]);
+
+    if (!electionActive) {
+      return { active: false, candidates: [] };
+    }
+
+    const candidateInfo = [];
+    for (const candidate of candidates) {
+      const votes = await contract.votes(candidate);
+      candidateInfo.push({
+        userId: candidate,
+        votes: Number(votes)
+      });
+    }
+
+    return {
+      active: true,
+      candidates: candidateInfo.sort((a, b) => b.votes - a.votes)
+    };
+  }
+
+  // ==================== FULL 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);
+    const info = await this.getContractInfo(address, flavor);
+    const members = await this.getMembers(address, flavor);
+
+    const snapshot = {
+      ...info,
+      members,
+      memberDetails: []
+    };
+
+    // Get member-specific details
+    for (const userId of members) {
+      const balance = await this.getUserEthBalance(address, flavor, userId);
+      const claimed = await this.hasClaimed(address, flavor, userId);
+
+      const memberDetail = {
+        userId,
+        ethBalance: balance,
+        hasClaimed: claimed
+      };
+
+      // Flavor-specific details
+      if (flavor === 'Splitter') {
+        const pct = await this.getSplitterUserPercentage(address, userId);
+        memberDetail.percentage = pct;
+      } else if (flavor === 'Zoned') {
+        memberDetail.zone = await this.getUserZone(address, userId);
+      } else if (flavor === 'Managed') {
+        memberDetail.appreciation = await this.getManagedAppreciation(address, userId);
+      } else if (flavor === 'Appreciative') {
+        memberDetail.appreciation = await this.getAppreciativePeer(address, userId);
+      } else if (flavor === 'Bundle') {
+        memberDetail.bundleInfo = await this.getBundleUserInfo(address, userId);
+      }
+
+      snapshot.memberDetails.push(memberDetail);
+    }
+
+    // Add flavor-specific configuration
+    if (flavor === 'Splitter') {
+      snapshot.split = await this.getSplitterSplit(address);
+      snapshot.children = await this.getSplitterChildren(address);
+    } else if (flavor === 'Zoned') {
+      snapshot.zoneConfig = await this.getZonedBreakdown(address);
+    } else if (flavor === 'Managed') {
+      snapshot.appreciationSummary = await this.getManagedAllAppreciation(address);
+    } else if (flavor === 'Appreciative') {
+      snapshot.appreciationSummary = await this.getAppreciativeAll(address);
+    } else if (flavor === 'Bundle') {
+      snapshot.bundleConfig = await this.getBundleConfig(address);
+      snapshot.bundleSplit = await this.getBundleSplit(address);
+      snapshot.bundleZones = await this.getBundleZoneBreakdown(address);
+      snapshot.election = await this.getBundleElection(address);
+    }
+
+    return snapshot;
+  }
+}
+
+export default ContractQueries;