holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/src/contracts/holon-contracts.js

@@ -0,0 +1,359 @@
+/**
+ * @fileoverview Per-holon contract management for Holosphere.
+ * Links holons to their smart contracts for fractal fund distribution.
+ * @module contracts/holon-contracts
+ */
+
+import { ContractDeployer, ABIs } from './deployer.js';
+import { ContractOperations } from './operations.js';
+
+/**
+ * Manages the mapping between holons and their deployed contracts.
+ * Provides deployment, linking, and retrieval operations.
+ * @class
+ */
+export class HolonContracts {
+  /**
+   * Create a new HolonContracts instance.
+   * @param {ChainManager} chainManager - Chain manager instance
+   * @param {ContractDeployer} [deployer] - Contract deployer instance (auto-created if not provided)
+   */
+  constructor(chainManager, deployer) {
+    this.chainManager = chainManager;
+    this.deployer = deployer || new ContractDeployer(chainManager);
+
+    // Maps holonId -> { address, type, contract, operations }
+    this.holonContracts = new Map();
+
+    // Storage for persistence (can be overridden)
+    this.storage = null;
+  }
+
+  /**
+   * Set storage adapter for persisting holon-contract mappings.
+   * @param {Object} storage - Storage adapter with get/set/delete methods
+   */
+  setStorage(storage) {
+    this.storage = storage;
+  }
+
+  /**
+   * Deploy a new contract for a holon.
+   * @param {string} holonId - Holon identifier
+   * @param {string} [type='Splitter'] - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
+   * @param {Object} [options={}] - Deployment options (varies by contract type)
+   * @returns {Promise<{contract: Object, address: string, operations: ContractOperations, txHash: string, type: string}>} Deployment details
+   * @throws {Error} If holon already has a contract
+   */
+  async deploy(holonId, type = 'Splitter', options = {}) {
+    if (this.holonContracts.has(holonId)) {
+      throw new Error(`Holon ${holonId} already has a contract. Use unlink() first to remove it.`);
+    }
+
+    const name = options.name || holonId;
+    const creatorUserId = options.creatorUserId || holonId;
+    let result;
+
+    switch (type) {
+      case 'Splitter':
+        result = await this.deployer.deploySplitter(
+          holonId,
+          name,
+          options.splitPercentage || 70,
+          { creatorUserId, ...options }
+        );
+        break;
+
+      case 'Managed':
+        result = await this.deployer.deployManaged(name, options);
+        break;
+
+      case 'Zoned':
+        result = await this.deployer.deployZoned(name, options.nZones || 6, options);
+        break;
+
+      case 'Appreciative':
+        result = await this.deployer.deployAppreciative(name, creatorUserId, options);
+        break;
+
+      case 'Bundle':
+        result = await this.deployer.deployBundle(
+          name,
+          options.steepness,
+          options.nZones || 6,
+          { creatorUserId, ...options }
+        );
+        break;
+
+      default:
+        throw new Error(`Unknown contract type: ${type}`);
+    }
+
+    // Create operations wrapper
+    const operations = new ContractOperations(result.contract, type, this.chainManager);
+
+    // Store mapping
+    const holonData = {
+      holonId,
+      address: result.address,
+      type,
+      contract: result.contract,
+      operations,
+      deployedAt: new Date().toISOString(),
+      txHash: result.txHash
+    };
+
+    this.holonContracts.set(holonId, holonData);
+
+    // Persist if storage available
+    await this._saveMapping(holonId, holonData);
+
+    return {
+      contract: result.contract,
+      address: result.address,
+      operations,
+      txHash: result.txHash,
+      type
+    };
+  }
+
+  /**
+   * Link a holon to an existing deployed contract.
+   * @param {string} holonId - Holon identifier
+   * @param {string} contractAddress - Existing contract address
+   * @param {string} [type='Splitter'] - Contract type
+   * @returns {Promise<{contract: Object, address: string, operations: ContractOperations, type: string}>} Link details
+   * @throws {Error} If holon already has a contract or contract is invalid
+   */
+  async link(holonId, contractAddress, type = 'Splitter') {
+    if (this.holonContracts.has(holonId)) {
+      throw new Error(`Holon ${holonId} already has a contract. Use unlink() first.`);
+    }
+
+    const abi = ABIs[type];
+    if (!abi) {
+      throw new Error(`Unknown contract type: ${type}`);
+    }
+
+    // Create contract instance
+    const contract = await this.chainManager.getContract(contractAddress, abi.abi);
+
+    // Verify it's a valid contract by calling a read method
+    try {
+      await contract.name();
+    } catch (error) {
+      throw new Error(`Invalid contract at ${contractAddress}: ${error.message}`);
+    }
+
+    // Create operations wrapper
+    const operations = new ContractOperations(contract, type, this.chainManager);
+
+    // Store mapping
+    const holonData = {
+      holonId,
+      address: contractAddress,
+      type,
+      contract,
+      operations,
+      linkedAt: new Date().toISOString()
+    };
+
+    this.holonContracts.set(holonId, holonData);
+
+    // Persist if storage available
+    await this._saveMapping(holonId, holonData);
+
+    return {
+      contract,
+      address: contractAddress,
+      operations,
+      type
+    };
+  }
+
+  /**
+   * Unlink a holon from its contract.
+   * @param {string} holonId - Holon identifier
+   * @returns {Promise<boolean>} True if unlinked, false if no contract was linked
+   */
+  async unlink(holonId) {
+    if (!this.holonContracts.has(holonId)) {
+      return false;
+    }
+
+    this.holonContracts.delete(holonId);
+
+    // Remove from storage if available
+    if (this.storage) {
+      await this.storage.delete?.(`holon_contract:${holonId}`);
+    }
+
+    return true;
+  }
+
+  /**
+   * Get contract instance for a holon.
+   * @param {string} holonId - Holon identifier
+   * @returns {Object|null} Ethers.js Contract instance or null if not found
+   */
+  getContract(holonId) {
+    const data = this.holonContracts.get(holonId);
+    return data?.contract || null;
+  }
+
+  /**
+   * Get contract address for a holon.
+   * @param {string} holonId - Holon identifier
+   * @returns {string|null} Contract address or null if not found
+   */
+  getAddress(holonId) {
+    const data = this.holonContracts.get(holonId);
+    return data?.address || null;
+  }
+
+  /**
+   * Get operations wrapper for a holon.
+   * @param {string} holonId - Holon identifier
+   * @returns {ContractOperations|null} Operations wrapper or null if not found
+   */
+  getOperations(holonId) {
+    const data = this.holonContracts.get(holonId);
+    return data?.operations || null;
+  }
+
+  /**
+   * Get contract type for a holon.
+   * @param {string} holonId - Holon identifier
+   * @returns {string|null} Contract type or null if not found
+   */
+  getType(holonId) {
+    const data = this.holonContracts.get(holonId);
+    return data?.type || null;
+  }
+
+  /**
+   * Check if a holon has a linked contract.
+   * @param {string} holonId - Holon identifier
+   * @returns {boolean} True if holon has a contract
+   */
+  hasContract(holonId) {
+    return this.holonContracts.has(holonId);
+  }
+
+  /**
+   * Get all holon-contract mappings.
+   * @returns {Array<{holonId: string, address: string, type: string, deployedAt?: string, linkedAt?: string}>} Array of mappings
+   */
+  listAll() {
+    const result = [];
+    for (const [holonId, data] of this.holonContracts) {
+      result.push({
+        holonId,
+        address: data.address,
+        type: data.type,
+        deployedAt: data.deployedAt,
+        linkedAt: data.linkedAt
+      });
+    }
+    return result;
+  }
+
+  /**
+   * Get holons by contract type.
+   * @param {string} type - Contract type
+   * @returns {Array<{holonId: string, address: string}>} Array of holons with matching type
+   */
+  getByType(type) {
+    const result = [];
+    for (const [holonId, data] of this.holonContracts) {
+      if (data.type === type) {
+        result.push({
+          holonId,
+          address: data.address
+        });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Load holon-contract mappings from storage.
+   * @returns {Promise<number>} Number of mappings successfully loaded
+   */
+  async loadFromStorage() {
+    if (!this.storage) {
+      return 0;
+    }
+
+    const mappings = await this.storage.get?.('holon_contracts_index') || [];
+    let loaded = 0;
+
+    for (const holonId of mappings) {
+      try {
+        const data = await this.storage.get?.(`holon_contract:${holonId}`);
+        if (data && data.address && data.type) {
+          // Recreate contract instance
+          const abi = ABIs[data.type];
+          if (abi) {
+            const contract = await this.chainManager.getContract(data.address, abi.abi);
+            const operations = new ContractOperations(contract, data.type, this.chainManager);
+
+            this.holonContracts.set(holonId, {
+              ...data,
+              contract,
+              operations
+            });
+            loaded++;
+          }
+        }
+      } catch (error) {
+        console.warn(`Failed to load contract for holon ${holonId}: ${error.message}`);
+      }
+    }
+
+    return loaded;
+  }
+
+  /**
+   * Save a holon-contract mapping to storage.
+   * @private
+   * @param {string} holonId - Holon identifier
+   * @param {Object} data - Holon contract data
+   */
+  async _saveMapping(holonId, data) {
+    if (!this.storage) return;
+
+    // Save the mapping (without contract/operations which can't be serialized)
+    await this.storage.set?.(`holon_contract:${holonId}`, {
+      holonId: data.holonId,
+      address: data.address,
+      type: data.type,
+      deployedAt: data.deployedAt,
+      linkedAt: data.linkedAt,
+      txHash: data.txHash
+    });
+
+    // Update index
+    const index = await this.storage.get?.('holon_contracts_index') || [];
+    if (!index.includes(holonId)) {
+      index.push(holonId);
+      await this.storage.set?.('holon_contracts_index', index);
+    }
+  }
+
+  /**
+   * Get required holon operations, throwing if not linked.
+   * @param {string} holonId - Holon identifier
+   * @returns {ContractOperations} Operations wrapper
+   * @throws {Error} If holon has no linked contract
+   */
+  requireOperations(holonId) {
+    const ops = this.getOperations(holonId);
+    if (!ops) {
+      throw new Error(`Holon ${holonId} has no linked contract. Deploy or link one first.`);
+    }
+    return ops;
+  }
+}
+
+export default HolonContracts;

package/src/contracts/index.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Holosphere Contracts Module - Smart contract integration for fractal fund distribution.
+ * Provides a complete toolkit for deploying, managing, and interacting with Holosphere smart contracts.
+ * @module contracts
+ */
+
+// Core classes
+export { ChainManager } from './chain-manager.js';
+export { ContractDeployer, ABIs } from './deployer.js';
+export { HolonContracts } from './holon-contracts.js';
+export { ContractOperations } from './operations.js';
+export { EventListener, SANKEY_EVENTS } from './event-listener.js';
+export { ContractQueries } from './queries.js';
+
+// Network utilities
+export {
+  NETWORKS,
+  getNetwork,
+  getNetworksByType,
+  listNetworks,
+  isNetworkSupported,
+  getTxUrl,
+  getAddressUrl
+} from './networks.js';
+
+// Re-export ABIs for direct access
+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' };
+import TestTokenABI from './abis/TestToken.json' with { type: 'json' };
+
+export const ContractABIs = {
+  Splitter: SplitterABI,
+  Managed: ManagedABI,
+  Zoned: ZonedABI,
+  Appreciative: AppreciativeABI,
+  Bundle: BundleABI,
+  Holons: HolonsABI,
+  TestToken: TestTokenABI
+};
+
+// Import for default export
+import { ChainManager } from './chain-manager.js';
+import { ContractDeployer } from './deployer.js';
+import { HolonContracts } from './holon-contracts.js';
+import { ContractOperations } from './operations.js';
+import { EventListener, SANKEY_EVENTS } from './event-listener.js';
+import { ContractQueries } from './queries.js';
+import { NETWORKS } from './networks.js';
+
+/**
+ * Create a complete contracts module instance with all components initialized.
+ * @param {Object} [config={}] - Configuration options for ChainManager
+ * @returns {Promise<{chainManager: ChainManager, deployer: ContractDeployer, holonContracts: HolonContracts}>} Initialized contracts module
+ */
+export async function createContractsModule(config = {}) {
+  const chainManager = new ChainManager(config);
+  const deployer = new ContractDeployer(chainManager);
+  const holonContracts = new HolonContracts(chainManager, deployer);
+
+  return {
+    chainManager,
+    deployer,
+    holonContracts
+  };
+}
+
+export default {
+  ChainManager,
+  ContractDeployer,
+  HolonContracts,
+  ContractOperations,
+  EventListener,
+  ContractQueries,
+  SANKEY_EVENTS,
+  NETWORKS,
+  ABIs: ContractABIs,
+  createContractsModule
+};

package/src/contracts/networks.js

@@ -0,0 +1,229 @@
+/**
+ * @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: {
+    name: 'Ethereum Mainnet',
+    chainId: 1,
+    rpc: 'https://eth.llamarpc.com',
+    explorer: 'https://etherscan.io',
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'mainnet'
+  },
+  polygon: {
+    name: 'Polygon Mainnet',
+    chainId: 137,
+    rpc: 'https://polygon-rpc.com',
+    explorer: 'https://polygonscan.com',
+    currency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
+    type: 'mainnet'
+  },
+  arbitrum: {
+    name: 'Arbitrum One',
+    chainId: 42161,
+    rpc: 'https://arb1.arbitrum.io/rpc',
+    explorer: 'https://arbiscan.io',
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'mainnet'
+  },
+  base: {
+    name: 'Base',
+    chainId: 8453,
+    rpc: 'https://mainnet.base.org',
+    explorer: 'https://basescan.org',
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'mainnet'
+  },
+  optimism: {
+    name: 'Optimism',
+    chainId: 10,
+    rpc: 'https://mainnet.optimism.io',
+    explorer: 'https://optimistic.etherscan.io',
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'mainnet'
+  },
+  avalanche: {
+    name: 'Avalanche C-Chain',
+    chainId: 43114,
+    rpc: 'https://api.avax.network/ext/bc/C/rpc',
+    explorer: 'https://snowtrace.io',
+    currency: { name: 'AVAX', symbol: 'AVAX', decimals: 18 },
+    type: 'mainnet'
+  },
+  bsc: {
+    name: 'BNB Smart Chain',
+    chainId: 56,
+    rpc: 'https://bsc-dataseed.binance.org',
+    explorer: 'https://bscscan.com',
+    currency: { name: 'BNB', symbol: 'BNB', decimals: 18 },
+    type: 'mainnet'
+  },
+
+  // ========== TESTNETS ==========
+  sepolia: {
+    name: 'Sepolia',
+    chainId: 11155111,
+    rpc: 'https://rpc.sepolia.org',
+    explorer: 'https://sepolia.etherscan.io',
+    currency: { name: 'Sepolia ETH', symbol: 'ETH', decimals: 18 },
+    type: 'testnet',
+    faucet: 'https://sepoliafaucet.com'
+  },
+  goerli: {
+    name: 'Goerli',
+    chainId: 5,
+    rpc: 'https://rpc.goerli.eth.gateway.fm',
+    explorer: 'https://goerli.etherscan.io',
+    currency: { name: 'Goerli ETH', symbol: 'ETH', decimals: 18 },
+    type: 'testnet',
+    faucet: 'https://goerlifaucet.com'
+  },
+  mumbai: {
+    name: 'Polygon Mumbai',
+    chainId: 80001,
+    rpc: 'https://rpc-mumbai.maticvigil.com',
+    explorer: 'https://mumbai.polygonscan.com',
+    currency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
+    type: 'testnet',
+    faucet: 'https://faucet.polygon.technology'
+  },
+  amoy: {
+    name: 'Polygon Amoy',
+    chainId: 80002,
+    rpc: 'https://rpc-amoy.polygon.technology',
+    explorer: 'https://amoy.polygonscan.com',
+    currency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
+    type: 'testnet',
+    faucet: 'https://faucet.polygon.technology'
+  },
+  arbitrumSepolia: {
+    name: 'Arbitrum Sepolia',
+    chainId: 421614,
+    rpc: 'https://sepolia-rollup.arbitrum.io/rpc',
+    explorer: 'https://sepolia.arbiscan.io',
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'testnet'
+  },
+  baseSepolia: {
+    name: 'Base Sepolia',
+    chainId: 84532,
+    rpc: 'https://sepolia.base.org',
+    explorer: 'https://sepolia.basescan.org',
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'testnet'
+  },
+  optimismSepolia: {
+    name: 'Optimism Sepolia',
+    chainId: 11155420,
+    rpc: 'https://sepolia.optimism.io',
+    explorer: 'https://sepolia-optimism.etherscan.io',
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'testnet'
+  },
+
+  // ========== LOCAL ==========
+  hardhat: {
+    name: 'Hardhat Local',
+    chainId: 31337,
+    rpc: 'http://127.0.0.1:8545',
+    explorer: null,
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'local'
+  },
+  anvil: {
+    name: 'Anvil Local',
+    chainId: 31337,
+    rpc: 'http://127.0.0.1:8545',
+    explorer: null,
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'local'
+  },
+  ganache: {
+    name: 'Ganache Local',
+    chainId: 1337,
+    rpc: 'http://127.0.0.1:7545',
+    explorer: null,
+    currency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    type: 'local'
+  }
+};
+
+/**
+ * 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') {
+    return NETWORKS[networkOrChainId] || null;
+  }
+  // Search by chain ID
+  for (const [name, config] of Object.entries(NETWORKS)) {
+    if (config.chainId === networkOrChainId) {
+      return { ...config, key: name };
+    }
+  }
+  return null;
+}
+
+/**
+ * Get all networks of a specific type.
+ * @param {'mainnet'|'testnet'|'local'} type - Network type
+ * @returns {Object} Map of networks matching the specified type
+ */
+export function getNetworksByType(type) {
+  return Object.fromEntries(
+    Object.entries(NETWORKS).filter(([_, config]) => config.type === type)
+  );
+}
+
+/**
+ * List all available network names.
+ * @returns {string[]} Array of network names
+ */
+export function listNetworks() {
+  return Object.keys(NETWORKS);
+}
+
+/**
+ * Check if a network is supported.
+ * @param {string} network - Network name
+ * @returns {boolean} True if network is supported
+ */
+export function isNetworkSupported(network) {
+  return network in NETWORKS;
+}
+
+/**
+ * Get block explorer URL for a transaction.
+ * @param {string} network - Network name
+ * @param {string} txHash - Transaction hash
+ * @returns {string|null} Explorer URL or null if network has no explorer
+ */
+export function getTxUrl(network, txHash) {
+  const config = NETWORKS[network];
+  if (!config?.explorer) return null;
+  return `${config.explorer}/tx/${txHash}`;
+}
+
+/**
+ * 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 if network has no explorer
+ */
+export function getAddressUrl(network, address) {
+  const config = NETWORKS[network];
+  if (!config?.explorer) return null;
+  return `${config.explorer}/address/${address}`;
+}
+
+export default NETWORKS;