holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/contracts/abis/ZonedFactory.json

@@ -0,0 +1,154 @@
+[
+  {
+    "type": "constructor",
+    "inputs": [
+      {
+        "name": "_botAddress",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "botAddress",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "createZoned",
+    "inputs": [
+      {
+        "name": "_creatorUserId",
+        "type": "string",
+        "internalType": "string"
+      },
+      {
+        "name": "_name",
+        "type": "string",
+        "internalType": "string"
+      },
+      {
+        "name": "_parameter",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "listHolons",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address[]",
+        "internalType": "address[]"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "listHolonsOf",
+    "inputs": [
+      {
+        "name": "_address",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address[]",
+        "internalType": "address[]"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "newHolon",
+    "inputs": [
+      {
+        "name": "creatorUserId",
+        "type": "string",
+        "internalType": "string"
+      },
+      {
+        "name": "_name",
+        "type": "string",
+        "internalType": "string"
+      },
+      {
+        "name": "_parameter",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "toAddress",
+    "inputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "event",
+    "name": "NewHolon",
+    "inputs": [
+      {
+        "name": "name",
+        "type": "string",
+        "indexed": false,
+        "internalType": "string"
+      },
+      {
+        "name": "addr",
+        "type": "address",
+        "indexed": false,
+        "internalType": "address"
+      }
+    ],
+    "anonymous": false
+  }
+]

package/src/contracts/chain-manager.js

@@ -0,0 +1,403 @@
+/**
+ * @fileoverview Multi-chain connection manager for Holosphere smart contracts.
+ * Handles provider/signer setup, network switching, and wallet management across EVM chains.
+ * @module contracts/chain-manager
+ */
+
+import { NETWORKS, getNetwork, isNetworkSupported } from './networks.js';
+
+/**
+ * Multi-chain connection manager for Holosphere contracts.
+ * Supports both RPC providers and browser wallets (MetaMask, etc.).
+ * @class
+ */
+export class ChainManager {
+  /**
+   * Create a new ChainManager instance.
+   * @param {Object} [config={}] - Configuration options
+   */
+  constructor(config = {}) {
+    this.config = config;
+    this.provider = null;
+    this.signer = null;
+    this.network = null;
+    this.networkName = null;
+    this.ethers = null;
+    this._initialized = false;
+  }
+
+  /**
+   * Initialize ethers.js library (lazy load).
+   * @private
+   * @returns {Promise<Object>} Ethers.js module
+   */
+  async _loadEthers() {
+    if (!this.ethers) {
+      // Dynamic import for ethers
+      const ethersModule = await import('ethers');
+      this.ethers = ethersModule;
+    }
+    return this.ethers;
+  }
+
+  /**
+   * Connect to a network using RPC provider.
+   * @param {string} networkName - Network name (e.g., 'sepolia', 'polygon')
+   * @param {string} [privateKey] - Private key for signing transactions
+   * @param {string} [rpcUrl] - Custom RPC URL (overrides default)
+   * @returns {Promise<{provider: Object, signer: Object|null, network: Object, networkName: string, config: Object}>} Connection details
+   * @throws {Error} If network is unsupported and no custom RPC URL provided
+   */
+  async connect(networkName, privateKey, rpcUrl) {
+    const ethers = await this._loadEthers();
+
+    if (!isNetworkSupported(networkName) && !rpcUrl) {
+      throw new Error(`Unsupported network: ${networkName}. Use a custom rpcUrl or choose from: ${Object.keys(NETWORKS).join(', ')}`);
+    }
+
+    const networkConfig = getNetwork(networkName) || { chainId: 0, name: networkName };
+    const url = rpcUrl || networkConfig.rpc;
+
+    // Create provider
+    this.provider = new ethers.JsonRpcProvider(url, {
+      chainId: networkConfig.chainId,
+      name: networkConfig.name
+    });
+
+    // Wait for provider to be ready
+    await this.provider.ready;
+
+    // Get actual network info
+    this.network = await this.provider.getNetwork();
+    this.networkName = networkName;
+
+    // Create signer if private key provided
+    if (privateKey) {
+      // Remove 0x prefix if present
+      const cleanKey = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
+      this.signer = new ethers.Wallet(cleanKey, this.provider);
+    }
+
+    this._initialized = true;
+
+    return {
+      provider: this.provider,
+      signer: this.signer,
+      network: this.network,
+      networkName: this.networkName,
+      config: networkConfig
+    };
+  }
+
+  /**
+   * Connect using browser wallet (MetaMask, etc.).
+   * @param {string} [networkName] - Optionally switch to this network
+   * @returns {Promise<{provider: Object, signer: Object, network: Object, address: string}>} Connection details including user address
+   * @throws {Error} If no browser wallet is detected
+   */
+  async connectBrowser(networkName) {
+    const ethers = await this._loadEthers();
+
+    if (typeof window === 'undefined' || !window.ethereum) {
+      throw new Error('No browser wallet detected. Please install MetaMask or another Web3 wallet.');
+    }
+
+    // Request account access
+    await window.ethereum.request({ method: 'eth_requestAccounts' });
+
+    // Create provider from browser
+    this.provider = new ethers.BrowserProvider(window.ethereum);
+    this.signer = await this.provider.getSigner();
+    this.network = await this.provider.getNetwork();
+
+    // Switch network if requested
+    if (networkName && isNetworkSupported(networkName)) {
+      const targetConfig = getNetwork(networkName);
+      if (this.network.chainId !== BigInt(targetConfig.chainId)) {
+        await this.switchNetwork(networkName);
+      }
+    }
+
+    const address = await this.signer.getAddress();
+    this._initialized = true;
+
+    return {
+      provider: this.provider,
+      signer: this.signer,
+      network: this.network,
+      address
+    };
+  }
+
+  /**
+   * Switch to a different network (browser wallet only).
+   * Adds the network to the wallet if it doesn't exist.
+   * @param {string} networkName - Target network name
+   * @returns {Promise<void>}
+   * @throws {Error} If not using a browser wallet or network is unknown
+   */
+  async switchNetwork(networkName) {
+    if (typeof window === 'undefined' || !window.ethereum) {
+      throw new Error('Network switching requires a browser wallet');
+    }
+
+    const config = getNetwork(networkName);
+    if (!config) {
+      throw new Error(`Unknown network: ${networkName}`);
+    }
+
+    const chainIdHex = '0x' + config.chainId.toString(16);
+
+    try {
+      // Try to switch to the network
+      await window.ethereum.request({
+        method: 'wallet_switchEthereumChain',
+        params: [{ chainId: chainIdHex }]
+      });
+    } catch (switchError) {
+      // If the network doesn't exist, add it
+      if (switchError.code === 4902) {
+        await window.ethereum.request({
+          method: 'wallet_addEthereumChain',
+          params: [{
+            chainId: chainIdHex,
+            chainName: config.name,
+            nativeCurrency: config.currency,
+            rpcUrls: [config.rpc],
+            blockExplorerUrls: config.explorer ? [config.explorer] : []
+          }]
+        });
+      } else {
+        throw switchError;
+      }
+    }
+
+    // Refresh provider/signer after network switch
+    const ethers = await this._loadEthers();
+    this.provider = new ethers.BrowserProvider(window.ethereum);
+    this.signer = await this.provider.getSigner();
+    this.network = await this.provider.getNetwork();
+    this.networkName = networkName;
+  }
+
+  /**
+   * Get the current provider.
+   * @returns {Object} Ethers.js provider instance
+   * @throws {Error} If not initialized
+   */
+  getProvider() {
+    this._requireInitialized();
+    return this.provider;
+  }
+
+  /**
+   * Get the current signer.
+   * @returns {Object} Ethers.js signer instance
+   * @throws {Error} If not initialized or no signer available
+   */
+  getSigner() {
+    this._requireInitialized();
+    if (!this.signer) {
+      throw new Error('No signer available. Connect with a private key or use connectBrowser().');
+    }
+    return this.signer;
+  }
+
+  /**
+   * Get the connected wallet address.
+   * @returns {Promise<string>} Ethereum address
+   * @throws {Error} If no signer available
+   */
+  async getAddress() {
+    const signer = this.getSigner();
+    return signer.getAddress();
+  }
+
+  /**
+   * Get ETH balance of an address.
+   * @param {string} [address] - Address to check (defaults to signer)
+   * @returns {Promise<string>} Balance in ETH as decimal string
+   * @throws {Error} If not initialized or no address/signer available
+   */
+  async getBalance(address) {
+    this._requireInitialized();
+    const ethers = await this._loadEthers();
+    const addr = address || (this.signer ? await this.signer.getAddress() : null);
+    if (!addr) {
+      throw new Error('No address provided and no signer available');
+    }
+    const balance = await this.provider.getBalance(addr);
+    return ethers.formatEther(balance);
+  }
+
+  /**
+   * Get current network configuration.
+   * @returns {Object} Network configuration object
+   * @throws {Error} If not initialized
+   */
+  getNetworkConfig() {
+    this._requireInitialized();
+    return getNetwork(this.networkName);
+  }
+
+  /**
+   * Get current chain ID.
+   * @returns {number} Chain ID as number
+   * @throws {Error} If not initialized
+   */
+  getChainId() {
+    this._requireInitialized();
+    return Number(this.network.chainId);
+  }
+
+  /**
+   * Check if connected to the expected network.
+   * @param {string} expectedNetwork - Expected network name
+   * @returns {boolean} True if on expected network
+   */
+  isOnNetwork(expectedNetwork) {
+    if (!this._initialized) return false;
+    const expected = getNetwork(expectedNetwork);
+    if (!expected) return false;
+    return this.getChainId() === expected.chainId;
+  }
+
+  /**
+   * Create a contract instance.
+   * @param {string} address - Contract address
+   * @param {Array} abi - Contract ABI
+   * @param {boolean} [useSigner=true] - Use signer for write operations
+   * @returns {Promise<Object>} Ethers.js Contract instance
+   * @throws {Error} If not initialized
+   */
+  async getContract(address, abi, useSigner = true) {
+    this._requireInitialized();
+    const ethers = await this._loadEthers();
+    const signerOrProvider = useSigner && this.signer ? this.signer : this.provider;
+    return new ethers.Contract(address, abi, signerOrProvider);
+  }
+
+  /**
+   * Deploy a contract.
+   * @param {Array} abi - Contract ABI
+   * @param {string} bytecode - Contract bytecode
+   * @param {Array} [constructorArgs=[]] - Constructor arguments
+   * @returns {Promise<{contract: Object, address: string, deployTx: Object, txHash: string}>} Deployment details
+   * @throws {Error} If not initialized or no signer available
+   */
+  async deployContract(abi, bytecode, constructorArgs = []) {
+    this._requireInitialized();
+    if (!this.signer) {
+      throw new Error('Signer required for contract deployment');
+    }
+
+    const ethers = await this._loadEthers();
+    const factory = new ethers.ContractFactory(abi, bytecode, this.signer);
+    const contract = await factory.deploy(...constructorArgs);
+
+    // Wait for deployment
+    await contract.waitForDeployment();
+    const address = await contract.getAddress();
+    const deployTx = contract.deploymentTransaction();
+
+    return {
+      contract,
+      address,
+      deployTx,
+      txHash: deployTx?.hash
+    };
+  }
+
+  /**
+   * Wait for a transaction to be mined.
+   * @param {string} txHash - Transaction hash
+   * @param {number} [confirmations=1] - Number of confirmations to wait for
+   * @returns {Promise<Object>} Transaction receipt
+   * @throws {Error} If not initialized
+   */
+  async waitForTransaction(txHash, confirmations = 1) {
+    this._requireInitialized();
+    return this.provider.waitForTransaction(txHash, confirmations);
+  }
+
+  /**
+   * Estimate gas for a transaction.
+   * @param {Object} tx - Transaction object
+   * @returns {Promise<bigint>} Estimated gas amount
+   * @throws {Error} If not initialized
+   */
+  async estimateGas(tx) {
+    this._requireInitialized();
+    return this.provider.estimateGas(tx);
+  }
+
+  /**
+   * Get current gas price and fee data.
+   * @returns {Promise<{gasPrice: string|null, maxFeePerGas: string|null, maxPriorityFeePerGas: string|null}>} Fee data in gwei
+   * @throws {Error} If not initialized
+   */
+  async getGasPrice() {
+    this._requireInitialized();
+    const ethers = await this._loadEthers();
+    const feeData = await this.provider.getFeeData();
+    return {
+      gasPrice: feeData.gasPrice ? ethers.formatUnits(feeData.gasPrice, 'gwei') : null,
+      maxFeePerGas: feeData.maxFeePerGas ? ethers.formatUnits(feeData.maxFeePerGas, 'gwei') : null,
+      maxPriorityFeePerGas: feeData.maxPriorityFeePerGas ? ethers.formatUnits(feeData.maxPriorityFeePerGas, 'gwei') : null
+    };
+  }
+
+  /**
+   * Parse units (e.g., ETH to wei).
+   * @param {string|number} value - Value to parse
+   * @param {string|number} [unit='ether'] - Unit name or decimals
+   * @returns {Promise<bigint>} Parsed value as bigint
+   */
+  async parseUnits(value, unit = 'ether') {
+    const ethers = await this._loadEthers();
+    return ethers.parseUnits(value.toString(), unit);
+  }
+
+  /**
+   * Format units (e.g., wei to ETH).
+   * @param {bigint|string} value - Value to format
+   * @param {string|number} [unit='ether'] - Unit name or decimals
+   * @returns {Promise<string>} Formatted value as decimal string
+   */
+  async formatUnits(value, unit = 'ether') {
+    const ethers = await this._loadEthers();
+    return ethers.formatUnits(value, unit);
+  }
+
+  /**
+   * Check if manager is initialized.
+   * @private
+   * @throws {Error} If not initialized
+   */
+  _requireInitialized() {
+    if (!this._initialized) {
+      throw new Error('ChainManager not initialized. Call connect() or connectBrowser() first.');
+    }
+  }
+
+  /**
+   * Check if connected to a network.
+   * @returns {boolean} True if connected
+   */
+  isConnected() {
+    return this._initialized && this.provider !== null;
+  }
+
+  /**
+   * Disconnect and clean up resources.
+   */
+  disconnect() {
+    this.provider = null;
+    this.signer = null;
+    this.network = null;
+    this.networkName = null;
+    this._initialized = false;
+  }
+}
+
+export default ChainManager;