holosphere 2.0.0-alpha1 → 2.0.0-alpha4

package/docs/CONTRACTS.md

@@ -0,0 +1,797 @@
+# Holosphere Smart Contracts Integration
+
+This guide covers the smart contracts module in Holosphere, enabling fractal fund distribution where every holon can become a recipient of ETH/ERC20 tokens.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Quick Start](#quick-start)
+3. [Contract Types](#contract-types)
+4. [1-Click Deployment](#1-click-deployment)
+5. [Per-Holon Contracts](#per-holon-contracts)
+6. [All Contract Operations](#all-contract-operations)
+7. [Multi-Chain Support](#multi-chain-support)
+8. [Examples](#examples)
+
+---
+
+## Overview
+
+The contracts module integrates a hierarchical fund distribution system into Holosphere:
+
+```
+                    ┌─────────────────────┐
+                    │   Funds Received    │
+                    │   (ETH or ERC20)    │
+                    └──────────┬──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │      Splitter       │
+                    │   (70% / 30% split) │
+                    └──────────┬──────────┘
+                               │
+              ┌────────────────┴────────────────┐
+              │                                 │
+    ┌─────────▼─────────┐             ┌─────────▼─────────┐
+    │     Managed       │             │      Zoned        │
+    │ (Appreciation)    │             │   (Tier-based)    │
+    └─────────┬─────────┘             └─────────┬─────────┘
+              │                                 │
+    ┌─────────┴─────────┐             ┌─────────┴─────────┐
+    │                   │             │                   │
+  Alice(60%)        Bob(40%)      Zone3(high)       Zone1(low)
+```
+
+### Key Concepts
+
+- **Fractal Ownership**: Each holon can have its own smart contract
+- **String-based User IDs**: Members identified by strings (e.g., 'alice', 'telegram_12345')
+- **Accumulated Rewards**: Funds stored until claimed (users pay claim gas)
+- **Multiple Distribution Models**: Splitter, Managed, Zoned, Appreciative, Bundle
+
+---
+
+## Quick Start
+
+### Initialize Contracts
+
+```javascript
+import HoloSphere from 'holosphere';
+
+const hs = new HoloSphere({ appName: 'myapp' });
+
+// Connect to network with private key
+await hs.initContracts({
+  network: 'sepolia',  // or 'polygon', 'base', etc.
+  privateKey: process.env.PRIVATE_KEY
+});
+
+// Or connect with browser wallet (MetaMask)
+await hs.initContractsBrowser('polygon');
+```
+
+### Deploy Everything (1-Click)
+
+```javascript
+const deployment = await hs.deployContracts({
+  testTokenSupply: '1000000'  // Optional: deploy test ERC20
+});
+
+console.log(deployment);
+// {
+//   network: 'sepolia',
+//   chainId: 11155111,
+//   contracts: {
+//     holons: '0x...',           // Main registry
+//     managedFactory: '0x...',
+//     zonedFactory: '0x...',
+//     splitterFactory: '0x...',
+//     appreciativeFactory: '0x...',
+//     bundleFactory: '0x...',
+//     testToken: '0x...'
+//   }
+// }
+```
+
+### Create Holon with Contract
+
+```javascript
+// Deploy contract for a holon
+await hs.deployHolonContract('my_organization', 'Splitter', {
+  name: 'MyOrg',
+  splitPercentage: 70  // 70% internal, 30% external
+});
+
+// Add members
+await hs.contractAddMembers('my_organization', ['alice', 'bob', 'charlie']);
+
+// Send funds (they're distributed automatically!)
+await hs.contractSendEth('my_organization', '1.0');
+
+// Members claim their rewards
+await hs.contractClaim('my_organization', 'alice', '0xAliceWallet...');
+```
+
+---
+
+## Contract Types
+
+### 1. Splitter
+
+**Purpose**: Split incoming funds between internal and external distribution
+
+**Use Case**: Organizations with core team + external contributors
+
+```javascript
+await hs.deployHolonContract('org', 'Splitter', { splitPercentage: 70 });
+
+// Set split: 70% to internal (Managed), 30% to external (Zoned)
+await hs.contractSetSplit('org', 70, 30);
+
+// Create child contracts automatically
+// Splitter creates: org_managed and org_zoned
+```
+
+**How Rewards Flow**:
+1. Funds sent to Splitter
+2. 70% forwarded to Managed contract
+3. 30% forwarded to Zoned contract
+4. Each child distributes to its members
+
+### 2. Managed (Appreciation-Based)
+
+**Purpose**: Distribute funds based on admin-set appreciation weights
+
+**Use Case**: Core teams where leadership decides contribution weights
+
+```javascript
+await hs.deployHolonContract('team', 'Managed');
+
+// Add members
+await hs.contractAddMembers('team', ['alice', 'bob', 'charlie']);
+
+// Set appreciation weights (determines reward %)
+await hs.contractSetAppreciation('team',
+  ['alice', 'bob', 'charlie'],
+  [300, 200, 100]  // Alice:50%, Bob:33%, Charlie:17%
+);
+
+// When 1 ETH is received:
+// - Alice gets 0.5 ETH
+// - Bob gets 0.33 ETH
+// - Charlie gets 0.17 ETH
+```
+
+**Key Points**:
+- Only owner/bot can set appreciation
+- Appreciation is relative (300:200:100 = 3:2:1 ratio)
+- If no appreciation set, rewards split equally
+
+### 3. Zoned (Tier-Based)
+
+**Purpose**: Distribute funds based on contribution zones/tiers
+
+**Use Case**: Communities with different contribution levels
+
+```javascript
+await hs.deployHolonContract('community', 'Zoned', { nZones: 5 });
+
+// Add members and assign to zones
+await hs.contractAddMember('community', 'alice');
+await hs.contractAddToZone('community', 'admin', 'alice', 4);  // High tier
+
+await hs.contractAddMember('community', 'bob');
+await hs.contractAddToZone('community', 'admin', 'bob', 2);    // Medium tier
+
+await hs.contractAddMember('community', 'charlie');
+await hs.contractAddToZone('community', 'admin', 'charlie', 1); // Low tier
+```
+
+**Zone Reward Formula**:
+```
+reward_units = a × zone² + b × zone + c
+```
+
+Default: `a=0, b=0, c=1` (equal distribution)
+Quadratic: `a=1, b=1, c=0` (higher zones get exponentially more)
+
+```javascript
+// Set quadratic rewards (zone 4 gets much more than zone 1)
+await hs.contractSetZoneParams('community', 'admin', 1, 1, 0);
+```
+
+### 4. Appreciative (Peer-to-Peer)
+
+**Purpose**: Members give appreciation to each other; rewards based on received appreciation
+
+**Use Case**: DAOs, cooperatives, peer-evaluated teams
+
+```javascript
+await hs.deployHolonContract('dao', 'Appreciative');
+
+await hs.contractAddMembers('dao', ['alice', 'bob', 'charlie']);
+
+// Each member has 100 points to give
+// Alice appreciates Bob's work
+await hs.contractAppreciate('dao', 'alice', 'bob', 30);
+
+// Bob appreciates Charlie
+await hs.contractAppreciate('dao', 'bob', 'charlie', 50);
+
+// Charlie appreciates Alice
+await hs.contractAppreciate('dao', 'charlie', 'alice', 25);
+
+// Check appreciation stats
+const received = await hs.contractGetAppreciationReceived('dao', 'bob');  // 30
+const given = await hs.contractGetAppreciationGiven('dao', 'alice');      // 30
+const remaining = await hs.contractGetAppreciationRemaining('dao', 'alice'); // 70
+```
+
+### 5. Bundle (2-Way Split with Governance)
+
+**Purpose**: Advanced splitting with interior/exterior + election mechanism
+
+**Use Case**: Complex organizations needing governance rotation
+
+```javascript
+await hs.deployHolonContract('project', 'Bundle', {
+  steepness: '0.5',  // 50% decay per zone
+  nZones: 6
+});
+
+// Interior split (explicit percentages)
+await hs.contractSetInteriorSplit('project',
+  ['founder', 'cto'],
+  [60, 40]
+);
+
+// Exterior uses zone-based with steepness decay
+await hs.contractSetSteepness('project', '0.7');  // 70% decay
+
+// Governance: Run election for new owner
+await hs.contractStartElection('project');
+await hs.contractNominate('project');  // Caller nominates self
+await hs.contractVote('project', '0xNomineeAddress');
+await hs.contractFinalizeElection('project');
+```
+
+---
+
+## 1-Click Deployment
+
+Deploy the entire contract infrastructure with a single call:
+
+```javascript
+const deployment = await hs.deployContracts({
+  // Optional: bot address for member management (defaults to deployer)
+  botAddress: '0xBotAddress',
+
+  // Optional: deploy test ERC20 token
+  deployTestToken: true,
+  testTokenSupply: '1000000',
+
+  // Optional: progress callback
+  onProgress: ({ step, total, message, done, address }) => {
+    console.log(`[${step}/${total}] ${message}`);
+    if (done) console.log(`  -> ${address}`);
+  }
+});
+```
+
+**What Gets Deployed**:
+1. `ManagedFactory` - Creates Managed contracts
+2. `ZonedFactory` - Creates Zoned contracts
+3. `SplitterFactory` - Creates Splitter contracts
+4. `AppreciativeFactory` - Creates Appreciative contracts
+5. `BundleFactory` - Creates Bundle contracts
+6. `Holons` - Central registry
+7. `TestToken` (optional) - ERC20 for testing
+
+**Save Addresses for Later**:
+```javascript
+// Save deployment
+localStorage.setItem('deployment', JSON.stringify(deployment.contracts));
+
+// Load later
+const saved = JSON.parse(localStorage.getItem('deployment'));
+hs.loadDeployedContracts(saved);
+```
+
+---
+
+## Per-Holon Contracts
+
+Each holon can have its own smart contract (1:1 fractal mapping):
+
+### Deploy Contract for Holon
+
+```javascript
+// Deploy new contract
+const result = await hs.deployHolonContract(holonId, type, options);
+
+// Types: 'Splitter', 'Managed', 'Zoned', 'Appreciative', 'Bundle'
+
+// Examples:
+await hs.deployHolonContract('team_alpha', 'Managed');
+await hs.deployHolonContract('community', 'Zoned', { nZones: 6 });
+await hs.deployHolonContract('dao', 'Appreciative');
+await hs.deployHolonContract('org', 'Splitter', { splitPercentage: 70 });
+await hs.deployHolonContract('project', 'Bundle', { steepness: '0.5' });
+```
+
+### Link Existing Contract
+
+```javascript
+// Link holon to existing contract
+await hs.linkHolonContract('my_holon', '0xExistingContract', 'Splitter');
+
+// Check if linked
+const hasContract = hs.hasHolonContract('my_holon');  // true
+
+// Get address
+const address = hs.getHolonContractAddress('my_holon');
+```
+
+### Unlink Contract
+
+```javascript
+await hs.unlinkHolonContract('my_holon');
+```
+
+### List All Mappings
+
+```javascript
+const mappings = hs.listHolonContracts();
+// [
+//   { holonId: 'team_alpha', address: '0x...', type: 'Managed' },
+//   { holonId: 'community', address: '0x...', type: 'Zoned' }
+// ]
+```
+
+---
+
+## All Contract Operations
+
+### Member Management
+
+```javascript
+// Add single member
+await hs.contractAddMember(holonId, 'alice');
+
+// Add multiple members
+await hs.contractAddMembers(holonId, ['alice', 'bob', 'charlie']);
+
+// Check membership
+const isMember = await hs.contractIsMember(holonId, 'alice');  // true
+```
+
+### Fund Distribution
+
+```javascript
+// Send ETH (triggers distribution)
+await hs.contractSendEth(holonId, '1.0');  // 1 ETH
+
+// Trigger ERC20 reward distribution
+await hs.contractReward(holonId, tokenAddress, amount);
+
+// Check balances
+const ethBalance = await hs.contractGetEthBalance(holonId, 'alice');
+const tokenBalance = await hs.contractGetTokenBalance(holonId, 'alice', tokenAddress);
+
+// Claim rewards
+await hs.contractClaim(holonId, 'alice', '0xAliceWallet');
+```
+
+### Splitter Operations
+
+```javascript
+// Set split percentages
+await hs.contractSetSplit(holonId, 70, 30);  // 70% internal, 30% external
+
+// Get current split
+const { internal, external } = await hs.contractGetSplit(holonId);
+
+// Create child contracts
+await hs.contractCreateManaged(holonId, 'creator', 'ChildName');
+await hs.contractCreateZoned(holonId, 'creator', 'ChildName', 6);
+
+// List children
+const { keys, addresses } = await hs.contractGetChildContracts(holonId);
+```
+
+### Managed Operations
+
+```javascript
+// Set appreciation weights
+await hs.contractSetAppreciation(holonId,
+  ['alice', 'bob'],
+  [300, 200]  // Alice: 60%, Bob: 40%
+);
+
+// Get appreciation
+const appreciation = await hs.contractGetAppreciation(holonId, 'alice');
+const total = await hs.contractGetTotalAppreciation(holonId);
+```
+
+### Zoned Operations
+
+```javascript
+// Add to zone
+await hs.contractAddToZone(holonId, 'admin', 'alice', 3);
+
+// Remove from zone
+await hs.contractRemoveFromZone(holonId, 'admin', 'alice');
+
+// Get zone
+const zone = await hs.contractGetZone(holonId, 'alice');
+
+// Set reward formula: reward = a*zone² + b*zone + c
+await hs.contractSetZoneParams(holonId, 'admin', 1, 1, 0);
+```
+
+### Appreciative Operations
+
+```javascript
+// Give appreciation
+await hs.contractAppreciate(holonId, 'alice', 'bob', 25);
+
+// Check stats
+const given = await hs.contractGetAppreciationGiven(holonId, 'alice');
+const received = await hs.contractGetAppreciationReceived(holonId, 'bob');
+```
+
+### Bundle Operations
+
+```javascript
+// Set steepness (0.5 = 50% decay per zone)
+await hs.contractSetSteepness(holonId, '0.5');
+const steepness = await hs.contractGetSteepness(holonId);
+
+// Set interior split
+await hs.contractSetInteriorSplit(holonId, ['a', 'b'], [60, 40]);
+
+// Governance
+await hs.contractStartElection(holonId);
+await hs.contractNominate(holonId);
+await hs.contractVote(holonId, nomineeAddress);
+await hs.contractFinalizeElection(holonId);
+```
+
+### Read-Only Queries
+
+```javascript
+const name = await hs.contractGetName(holonId);
+const owner = await hs.contractGetOwner(holonId);
+const bot = await hs.contractGetBotAddress(holonId);
+const total = await hs.contractGetTotalDeposited(holonId, tokenAddress);
+```
+
+---
+
+## Multi-Chain Support
+
+### Supported Networks
+
+| Network | Chain ID | Type | Usage |
+|---------|----------|------|-------|
+| `ethereum` | 1 | Mainnet | Production |
+| `polygon` | 137 | Mainnet | Low fees |
+| `arbitrum` | 42161 | Mainnet | L2 |
+| `base` | 8453 | Mainnet | L2 |
+| `optimism` | 10 | Mainnet | L2 |
+| `sepolia` | 11155111 | Testnet | Testing |
+| `mumbai` | 80001 | Testnet | Testing |
+| `hardhat` | 31337 | Local | Development |
+| `anvil` | 31337 | Local | Development |
+
+### Connect to Different Networks
+
+```javascript
+// Testnet (recommended for testing)
+await hs.initContracts({
+  network: 'sepolia',
+  privateKey: process.env.PRIVATE_KEY
+});
+
+// Polygon (low fees)
+await hs.initContracts({
+  network: 'polygon',
+  privateKey: process.env.PRIVATE_KEY
+});
+
+// Custom RPC
+await hs.initContracts({
+  network: 'ethereum',
+  privateKey: process.env.PRIVATE_KEY,
+  rpcUrl: 'https://my-custom-rpc.com'
+});
+
+// Local development
+await hs.initContracts({
+  network: 'hardhat',
+  privateKey: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
+});
+```
+
+### Network Utilities
+
+```javascript
+import {
+  NETWORKS,
+  getNetwork,
+  getTxUrl,
+  getAddressUrl,
+  isNetworkSupported
+} from 'holosphere';
+
+// Get network config
+const config = getNetwork('polygon');
+// { name: 'Polygon Mainnet', chainId: 137, rpc: '...', ... }
+
+// Get explorer URLs
+const txUrl = getTxUrl('ethereum', '0xTxHash...');
+// https://etherscan.io/tx/0xTxHash...
+
+const addrUrl = getAddressUrl('polygon', '0xAddress...');
+// https://polygonscan.com/address/0xAddress...
+
+// Check support
+isNetworkSupported('polygon');  // true
+isNetworkSupported('solana');   // false
+```
+
+---
+
+## Examples
+
+### Example 1: Simple Team Distribution
+
+```javascript
+import HoloSphere from 'holosphere';
+
+async function setupTeam() {
+  const hs = new HoloSphere({ appName: 'myteam' });
+
+  // Connect to Sepolia testnet
+  await hs.initContracts({
+    network: 'sepolia',
+    privateKey: process.env.PRIVATE_KEY
+  });
+
+  // Deploy infrastructure
+  await hs.deployContracts();
+
+  // Create team contract
+  await hs.deployHolonContract('dev_team', 'Managed');
+
+  // Add team members
+  await hs.contractAddMembers('dev_team', ['alice', 'bob', 'charlie']);
+
+  // Set contributions (alice: 50%, bob: 30%, charlie: 20%)
+  await hs.contractSetAppreciation('dev_team',
+    ['alice', 'bob', 'charlie'],
+    [500, 300, 200]
+  );
+
+  // When client pays 1 ETH...
+  await hs.contractSendEth('dev_team', '1.0');
+
+  // Check balances
+  const aliceBalance = await hs.contractGetEthBalance('dev_team', 'alice');
+  console.log(`Alice can claim: ${aliceBalance} ETH`);  // ~0.5 ETH
+
+  // Alice claims her rewards
+  await hs.contractClaim('dev_team', 'alice', '0xAliceWallet');
+}
+```
+
+### Example 2: Organization with Departments
+
+```javascript
+async function setupOrganization() {
+  const hs = new HoloSphere({ appName: 'myorg' });
+  await hs.initContracts({ network: 'polygon', privateKey: KEY });
+  await hs.deployContracts();
+
+  // Main organization (Splitter)
+  await hs.deployHolonContract('organization', 'Splitter', {
+    name: 'Acme Corp',
+    splitPercentage: 60  // 60% internal, 40% external
+  });
+
+  // Get child contract addresses
+  const children = await hs.contractGetChildContracts('organization');
+  console.log('Managed:', children.addresses[0]);
+  console.log('Zoned:', children.addresses[1]);
+
+  // Now funds sent to organization automatically split:
+  // - 60% -> Managed (for core team)
+  // - 40% -> Zoned (for contributors)
+
+  // Configure the Managed child for core team
+  const managedHolon = 'organization_managed';
+  await hs.linkHolonContract(managedHolon, children.addresses[0], 'Managed');
+  await hs.contractAddMembers(managedHolon, ['ceo', 'cto', 'cfo']);
+  await hs.contractSetAppreciation(managedHolon,
+    ['ceo', 'cto', 'cfo'],
+    [400, 350, 250]
+  );
+
+  // Configure the Zoned child for contributors
+  const zonedHolon = 'organization_zoned';
+  await hs.linkHolonContract(zonedHolon, children.addresses[1], 'Zoned');
+  await hs.contractAddMembers(zonedHolon, ['dev1', 'dev2', 'designer']);
+  await hs.contractAddToZone(zonedHolon, 'admin', 'dev1', 3);
+  await hs.contractAddToZone(zonedHolon, 'admin', 'dev2', 2);
+  await hs.contractAddToZone(zonedHolon, 'admin', 'designer', 2);
+}
+```
+
+### Example 3: DAO with Peer Appreciation
+
+```javascript
+async function setupDAO() {
+  const hs = new HoloSphere({ appName: 'mydao' });
+  await hs.initContracts({ network: 'base', privateKey: KEY });
+  await hs.deployContracts();
+
+  // Create DAO with peer appreciation
+  await hs.deployHolonContract('dao', 'Appreciative');
+
+  // Add members
+  const members = ['alice', 'bob', 'charlie', 'david'];
+  await hs.contractAddMembers('dao', members);
+
+  // Members appreciate each other's contributions
+  // (Each has 100 points to distribute)
+
+  // Alice appreciates Bob and Charlie
+  await hs.contractAppreciate('dao', 'alice', 'bob', 40);
+  await hs.contractAppreciate('dao', 'alice', 'charlie', 30);
+
+  // Bob appreciates Alice and David
+  await hs.contractAppreciate('dao', 'bob', 'alice', 50);
+  await hs.contractAppreciate('dao', 'bob', 'david', 25);
+
+  // Check how much appreciation everyone received
+  for (const member of members) {
+    const received = await hs.contractGetAppreciationReceived('dao', member);
+    console.log(`${member} received ${received} appreciation`);
+  }
+
+  // Rewards distributed based on appreciation received!
+}
+```
+
+### Example 4: Browser Integration (MetaMask)
+
+```javascript
+async function connectWallet() {
+  const hs = new HoloSphere({ appName: 'dapp' });
+
+  // Connect with MetaMask
+  const { address, network } = await hs.initContractsBrowser('polygon');
+  console.log(`Connected: ${address} on ${network.name}`);
+
+  // Load existing deployment
+  const saved = localStorage.getItem('deployment');
+  if (saved) {
+    hs.loadDeployedContracts(JSON.parse(saved));
+  }
+
+  // User can now interact with contracts
+  // (MetaMask will prompt for each transaction)
+}
+```
+
+### Example 5: Progress Tracking for Deployment
+
+```javascript
+async function deployWithProgress() {
+  const hs = new HoloSphere({ appName: 'myapp' });
+  await hs.initContracts({ network: 'sepolia', privateKey: KEY });
+
+  const deployment = await hs.deployContracts({
+    testTokenSupply: '1000000',
+    onProgress: ({ step, total, message, done, address }) => {
+      const progress = Math.round((step / total) * 100);
+      console.log(`[${progress}%] ${message}`);
+
+      if (done && address) {
+        console.log(`  Contract deployed at: ${address}`);
+      }
+    }
+  });
+
+  // Output:
+  // [12%] Deploying ManagedFactory...
+  //   Contract deployed at: 0x...
+  // [25%] Deploying ZonedFactory...
+  //   Contract deployed at: 0x...
+  // ...
+
+  return deployment;
+}
+```
+
+---
+
+## API Reference
+
+### HoloSphere Contract Methods
+
+| Method | Description |
+|--------|-------------|
+| `initContracts(config)` | Initialize with private key |
+| `initContractsBrowser(network?)` | Initialize with browser wallet |
+| `deployContracts(options?)` | 1-click deploy all contracts |
+| `loadDeployedContracts(addresses)` | Load existing deployment |
+| `getDeployedContracts()` | Get deployed addresses |
+| `deployHolonContract(holonId, type, options?)` | Deploy contract for holon |
+| `linkHolonContract(holonId, address, type)` | Link existing contract |
+| `unlinkHolonContract(holonId)` | Remove contract link |
+| `hasHolonContract(holonId)` | Check if holon has contract |
+| `getHolonContractAddress(holonId)` | Get contract address |
+| `listHolonContracts()` | List all holon-contract mappings |
+| `contractAddMember(holonId, userId)` | Add member |
+| `contractAddMembers(holonId, userIds)` | Add multiple members |
+| `contractIsMember(holonId, userId)` | Check membership |
+| `contractSendEth(holonId, amount)` | Send ETH to contract |
+| `contractReward(holonId, token, amount)` | Trigger ERC20 distribution |
+| `contractClaim(holonId, userId, beneficiary)` | Claim rewards |
+| `contractGetEthBalance(holonId, userId)` | Get ETH balance |
+| `contractGetTokenBalance(holonId, userId, token)` | Get token balance |
+| `contractSetSplit(holonId, internal, external)` | Set Splitter percentages |
+| `contractGetSplit(holonId)` | Get Splitter percentages |
+| `contractSetAppreciation(holonId, users, amounts)` | Set Managed weights |
+| `contractGetAppreciation(holonId, userId)` | Get user appreciation |
+| `contractAddToZone(holonId, sender, user, zone)` | Add to Zoned tier |
+| `contractRemoveFromZone(holonId, sender, user)` | Remove from zone |
+| `contractGetZone(holonId, userId)` | Get user's zone |
+| `contractAppreciate(holonId, from, to, amount)` | Give peer appreciation |
+| `contractSetSteepness(holonId, steepness)` | Set Bundle decay |
+| `contractStartElection(holonId)` | Start Bundle election |
+| `contractVote(holonId, nominee)` | Vote in election |
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**"Contracts not initialized"**
+```javascript
+// Make sure to call initContracts first
+await hs.initContracts({ network: 'sepolia', privateKey: KEY });
+```
+
+**"Holon has no linked contract"**
+```javascript
+// Deploy or link a contract first
+await hs.deployHolonContract('myholon', 'Managed');
+// or
+await hs.linkHolonContract('myholon', '0xExisting...', 'Managed');
+```
+
+**"Operation only available for X contracts"**
+```javascript
+// Make sure you're using the right contract type
+// Splitter: setContractSplit, createManagedContract, etc.
+// Managed: setAppreciation, getAppreciation, etc.
+// Zoned: addToZone, removeFromZone, etc.
+// Appreciative: appreciate, getAppreciationGiven, etc.
+// Bundle: setSteepness, startElection, etc.
+```
+
+**"Insufficient funds"**
+```javascript
+// Check balance before transactions
+const balance = await hs.getChainManager().getBalance();
+console.log(`Balance: ${balance} ETH`);
+```
+
+---
+
+## License
+
+MIT License - See LICENSE file for details.