@megatao/sdk 1.1.0

package/docs/reference/TROUBLESHOOTING.md

@@ -0,0 +1,922 @@
+# Alpha Futures SDK Troubleshooting Guide
+
+## Table of Contents
+
+- [Common Issues](#common-issues)
+- [Installation Problems](#installation-problems)
+- [Connection Issues](#connection-issues)
+- [Transaction Errors](#transaction-errors)
+- [Position Management Issues](#position-management-issues)
+- [Gas and Fee Problems](#gas-and-fee-problems)
+- [Event and WebSocket Issues](#event-and-websocket-issues)
+- [Integration Specific Issues](#integration-specific-issues)
+- [Performance Issues](#performance-issues)
+- [Debugging Tools](#debugging-tools)
+- [FAQ](#faq)
+
+## Common Issues
+
+### Issue: "Cannot read property 'x' of undefined"
+
+**Symptoms:**
+```
+TypeError: Cannot read property 'openPosition' of undefined
+```
+
+**Causes:**
+- Client not properly initialized
+- Accessing property before async initialization completes
+
+**Solutions:**
+```typescript
+// ❌ Wrong
+const client = new AlphaFuturesClient(config);
+client.positionManager.openPosition(...); // May fail
+
+// ✅ Correct
+const client = new AlphaFuturesClient(config);
+// Wait for any async initialization if needed
+await client.initialize?.();
+await client.positionManager.openPosition(...);
+```
+
+### Issue: "Insufficient funds" or "Insufficient margin"
+
+**Symptoms:**
+- Transaction reverts with insufficient funds error
+- Cannot open position despite having TAO balance
+
+**Solutions:**
+```typescript
+// Check TAO balance
+const taoBalance = await provider.getBalance(address);
+console.log('TAO Balance:', ethers.formatEther(taoBalance));
+
+// Check margin account
+const marginAccount = await client.marginAccount.getMarginAccount(address);
+console.log('Available Margin:', ethers.formatEther(marginAccount.availableMargin));
+
+// Ensure you've deposited to margin account
+if (marginAccount.availableMargin === 0n) {
+  const tx = await client.marginAccount.deposit(ethers.parseEther('1000'));
+  await tx.wait();
+}
+```
+
+## Installation Problems
+
+### Issue: Module Resolution Errors
+
+**Symptoms:**
+```
+Error: Cannot find module '@alpha-futures/sdk'
+Module not found: Can't resolve 'ethers'
+```
+
+**Solutions:**
+
+1. **Verify installation:**
+```bash
+npm list @alpha-futures/sdk
+npm list ethers
+```
+
+2. **Clean install:**
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+3. **Check TypeScript config:**
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  }
+}
+```
+
+### Issue: Version Conflicts
+
+**Symptoms:**
+```
+npm ERR! peer dep missing: ethers@^6.0.0
+```
+
+**Solutions:**
+```bash
+# Check ethers version
+npm list ethers
+
+# Install compatible version
+npm install ethers@^6.0.0
+
+# Or use --legacy-peer-deps
+npm install @alpha-futures/sdk --legacy-peer-deps
+```
+
+## Connection Issues
+
+### Issue: "Provider not connected"
+
+**Symptoms:**
+- Cannot connect to network
+- Provider returns null/undefined
+
+**Solutions:**
+
+1. **Check RPC URL:**
+```typescript
+// Verify RPC is accessible
+try {
+  const provider = new ethers.JsonRpcProvider(rpcUrl);
+  const network = await provider.getNetwork();
+  console.log('Connected to:', network.name);
+} catch (error) {
+  console.error('RPC connection failed:', error);
+}
+```
+
+2. **Use fallback providers:**
+```typescript
+const providers = [
+  'https://primary-rpc.com',
+  'https://backup-rpc.com',
+  'https://fallback-rpc.com'
+];
+
+let provider;
+for (const url of providers) {
+  try {
+    provider = new ethers.JsonRpcProvider(url);
+    await provider.getNetwork();
+    console.log('Connected to:', url);
+    break;
+  } catch (error) {
+    console.error(`Failed to connect to ${url}`);
+  }
+}
+```
+
+### Issue: MetaMask Connection Problems
+
+**Symptoms:**
+- "MetaMask not installed"
+- Cannot get user accounts
+- Chain ID mismatch
+
+**Solutions:**
+
+1. **Check MetaMask availability:**
+```typescript
+if (typeof window.ethereum === 'undefined') {
+  console.error('MetaMask not installed');
+  // Redirect to MetaMask install page
+  window.open('https://metamask.io/download/', '_blank');
+  return;
+}
+```
+
+2. **Handle chain switching:**
+```typescript
+async function switchChain(chainId: number) {
+  try {
+    await window.ethereum.request({
+      method: 'wallet_switchEthereumChain',
+      params: [{ chainId: `0x${chainId.toString(16)}` }],
+    });
+  } catch (error) {
+    if (error.code === 4902) {
+      // Chain not added to MetaMask
+      await addChain(chainId);
+    } else {
+      throw error;
+    }
+  }
+}
+
+async function addChain(chainId: number) {
+  const chainData = getChainData(chainId); // Your chain config
+  await window.ethereum.request({
+    method: 'wallet_addEthereumChain',
+    params: [chainData],
+  });
+}
+```
+
+## Transaction Errors
+
+### Issue: "Transaction reverted"
+
+**Symptoms:**
+- Transaction fails with generic revert
+- No clear error message
+
+**Solutions:**
+
+1. **Simulate transaction first:**
+```typescript
+try {
+  // Simulate the transaction
+  await client.positionManager.callStatic.openPosition({
+    asset: 'ALPHA',
+    size: ethers.parseEther('1000'),
+    leverage: 3,
+    isLong: true
+  });
+  
+  // If simulation succeeds, send actual transaction
+  const tx = await client.positionManager.openPosition(...);
+} catch (error) {
+  console.error('Transaction would fail:', error.reason);
+}
+```
+
+2. **Decode revert reason:**
+```typescript
+async function decodeRevertReason(txHash: string) {
+  try {
+    const tx = await provider.getTransaction(txHash);
+    const code = await provider.call(tx, tx.blockNumber);
+    const reason = ethers.toUtf8String('0x' + code.substr(138));
+    console.log('Revert reason:', reason);
+  } catch (error) {
+    console.error('Could not decode revert reason');
+  }
+}
+```
+
+### Issue: "Nonce too low"
+
+**Symptoms:**
+- Transaction rejected with nonce error
+- Transactions stuck in pending
+
+**Solutions:**
+
+1. **Get correct nonce:**
+```typescript
+const nonce = await provider.getTransactionCount(address, 'pending');
+const tx = await client.positionManager.openPosition(params, { nonce });
+```
+
+2. **Reset nonce in MetaMask:**
+- Settings → Advanced → Reset Account
+- This clears pending transactions
+
+### Issue: "Gas estimation failed"
+
+**Solutions:**
+
+1. **Manual gas estimation:**
+```typescript
+try {
+  const estimatedGas = await client.positionManager.estimateGas.openPosition(params);
+  const gasLimit = estimatedGas * 120n / 100n; // Add 20% buffer
+  
+  const tx = await client.positionManager.openPosition(params, { gasLimit });
+} catch (error) {
+  // Use fallback gas limit
+  const tx = await client.positionManager.openPosition(params, { 
+    gasLimit: 500000n 
+  });
+}
+```
+
+2. **Check gas price:**
+```typescript
+const feeData = await provider.getFeeData();
+console.log('Gas price:', ethers.formatUnits(feeData.gasPrice, 'gwei'));
+
+// For EIP-1559
+console.log('Max fee:', ethers.formatUnits(feeData.maxFeePerGas, 'gwei'));
+console.log('Priority fee:', ethers.formatUnits(feeData.maxPriorityFeePerGas, 'gwei'));
+```
+
+## Position Management Issues
+
+### Issue: "Position not found"
+
+**Symptoms:**
+- getPosition returns error
+- Position ID seems invalid
+
+**Solutions:**
+
+1. **Verify position exists:**
+```typescript
+// Get all positions for user
+const positions = await client.positionManager.getAllPositions(address);
+console.log('User positions:', positions);
+
+// Check if position ID exists
+const positionExists = positions.some(p => p.id === positionId);
+if (!positionExists) {
+  console.error('Position does not exist');
+}
+```
+
+2. **Extract position ID from transaction:**
+```typescript
+async function getPositionIdFromTx(txHash: string): Promise<bigint> {
+  const receipt = await provider.getTransactionReceipt(txHash);
+  
+  // Find PositionOpened event
+  const iface = client.positionManager.interface;
+  const topic = iface.getEventTopic('PositionOpened');
+  
+  const log = receipt.logs.find(log => log.topics[0] === topic);
+  if (!log) throw new Error('PositionOpened event not found');
+  
+  // Decode event
+  const decoded = iface.decodeEventLog('PositionOpened', log.data, log.topics);
+  return decoded.positionId;
+}
+```
+
+### Issue: "Cannot close position"
+
+**Causes:**
+- Position already closed
+- Not position owner
+- Position is being liquidated
+
+**Solutions:**
+
+```typescript
+// Check position status
+const position = await client.positionManager.getPosition(positionId);
+console.log('Position owner:', position.trader);
+console.log('Current user:', await signer.getAddress());
+
+// Verify ownership
+if (position.trader.toLowerCase() !== (await signer.getAddress()).toLowerCase()) {
+  throw new Error('Not position owner');
+}
+
+// Check if position is liquidatable
+const liquidationStatus = await client.liquidationEngine.checkLiquidationStatus(positionId);
+if (liquidationStatus.canLiquidate) {
+  console.warn('Position is liquidatable, may fail to close normally');
+}
+```
+
+## Gas and Fee Problems
+
+### Issue: "Gas price too high"
+
+**Solutions:**
+
+1. **Implement gas price limits:**
+```typescript
+class GasManager {
+  private maxGasPrice: bigint;
+  
+  constructor(maxGweiPrice: number) {
+    this.maxGasPrice = ethers.parseUnits(maxGweiPrice.toString(), 'gwei');
+  }
+  
+  async waitForAcceptableGas(provider: Provider): Promise<void> {
+    while (true) {
+      const feeData = await provider.getFeeData();
+      if (feeData.gasPrice <= this.maxGasPrice) {
+        return;
+      }
+      
+      console.log('Gas too high, waiting...');
+      await new Promise(resolve => setTimeout(resolve, 60000)); // Wait 1 minute
+    }
+  }
+}
+```
+
+2. **Use gas price oracles:**
+```typescript
+async function getGasPriceRecommendation(): Promise<{
+  slow: bigint;
+  standard: bigint;
+  fast: bigint;
+}> {
+  // Example using etherscan gas oracle
+  const response = await fetch(
+    `https://api.etherscan.io/api?module=gastracker&action=gasoracle&apikey=${API_KEY}`
+  );
+  const data = await response.json();
+  
+  return {
+    slow: ethers.parseUnits(data.result.SafeGasPrice, 'gwei'),
+    standard: ethers.parseUnits(data.result.ProposeGasPrice, 'gwei'),
+    fast: ethers.parseUnits(data.result.FastGasPrice, 'gwei')
+  };
+}
+```
+
+### Issue: "Trading fees unexpectedly high"
+
+**Solutions:**
+
+```typescript
+// Calculate fees before trading
+const tradingFee = await client.positionManager.calculateTradingFee(positionSize);
+const gasEstimate = await client.positionManager.estimateGas.openPosition(params);
+const gasPrice = await provider.getGasPrice();
+const gasCost = gasEstimate * gasPrice;
+
+console.log('Trading fee:', ethers.formatEther(tradingFee));
+console.log('Gas cost:', ethers.formatEther(gasCost));
+console.log('Total cost:', ethers.formatEther(tradingFee + gasCost));
+```
+
+## Event and WebSocket Issues
+
+### Issue: "Missing events"
+
+**Symptoms:**
+- Events not firing
+- WebSocket disconnects
+
+**Solutions:**
+
+1. **Implement event recovery:**
+```typescript
+class EventMonitor {
+  private lastBlockProcessed: number = 0;
+  
+  async recoverMissedEvents(
+    contract: Contract,
+    eventName: string,
+    fromBlock: number
+  ): Promise<Event[]> {
+    const currentBlock = await contract.provider.getBlockNumber();
+    const events = await contract.queryFilter(
+      contract.filters[eventName](),
+      fromBlock,
+      currentBlock
+    );
+    
+    this.lastBlockProcessed = currentBlock;
+    return events;
+  }
+  
+  startMonitoring(contract: Contract, eventName: string) {
+    contract.on(eventName, (...args) => {
+      console.log(`${eventName} event:`, args);
+      this.lastBlockProcessed = args[args.length - 1].blockNumber;
+    });
+    
+    // Periodic recovery check
+    setInterval(async () => {
+      const missed = await this.recoverMissedEvents(
+        contract,
+        eventName,
+        this.lastBlockProcessed + 1
+      );
+      
+      if (missed.length > 0) {
+        console.log(`Recovered ${missed.length} missed events`);
+      }
+    }, 60000); // Check every minute
+  }
+}
+```
+
+2. **WebSocket reconnection:**
+```typescript
+class ReconnectingWebSocket {
+  private ws: WebSocket | null = null;
+  private reconnectInterval: number = 5000;
+  private shouldReconnect: boolean = true;
+  
+  connect(url: string) {
+    this.ws = new WebSocket(url);
+    
+    this.ws.onopen = () => {
+      console.log('WebSocket connected');
+      this.reconnectInterval = 5000; // Reset interval
+    };
+    
+    this.ws.onclose = () => {
+      if (this.shouldReconnect) {
+        console.log(`Reconnecting in ${this.reconnectInterval}ms...`);
+        setTimeout(() => this.connect(url), this.reconnectInterval);
+        this.reconnectInterval = Math.min(this.reconnectInterval * 2, 60000);
+      }
+    };
+    
+    this.ws.onerror = (error) => {
+      console.error('WebSocket error:', error);
+    };
+  }
+  
+  disconnect() {
+    this.shouldReconnect = false;
+    this.ws?.close();
+  }
+}
+```
+
+## Integration Specific Issues
+
+### React: "Invalid hook call"
+
+**Solutions:**
+
+1. **Check React versions:**
+```bash
+npm list react react-dom
+# Ensure only one version of React is installed
+```
+
+2. **Fix hook usage:**
+```typescript
+// ❌ Wrong - Hook in conditional
+function Component() {
+  if (someCondition) {
+    const { client } = useAlphaFutures(); // Error!
+  }
+}
+
+// ✅ Correct
+function Component() {
+  const { client } = useAlphaFutures();
+  
+  if (someCondition && client) {
+    // Use client
+  }
+}
+```
+
+### Next.js: "Window is not defined"
+
+**Solutions:**
+
+```typescript
+// Use dynamic imports for client-side only code
+import dynamic from 'next/dynamic';
+
+const TradingPanel = dynamic(
+  () => import('../components/TradingPanel'),
+  { ssr: false }
+);
+
+// Or check for browser environment
+if (typeof window !== 'undefined') {
+  // Browser-only code
+}
+```
+
+### Mobile: "WalletConnect issues"
+
+**Solutions:**
+
+```typescript
+// Implement proper WalletConnect initialization
+class WalletConnectManager {
+  private connector: WalletConnectProvider;
+  
+  async initialize() {
+    this.connector = new WalletConnectProvider({
+      infuraId: process.env.INFURA_ID,
+      qrcode: true,
+      bridge: 'https://bridge.walletconnect.org',
+    });
+    
+    // Subscribe to events
+    this.connector.on('connect', (error, payload) => {
+      if (error) {
+        console.error('WalletConnect error:', error);
+        return;
+      }
+      console.log('Connected:', payload);
+    });
+    
+    // Handle disconnect
+    this.connector.on('disconnect', (error, payload) => {
+      console.log('Disconnected');
+      // Clean up
+      this.connector = null;
+    });
+  }
+}
+```
+
+## Performance Issues
+
+### Issue: "Slow response times"
+
+**Solutions:**
+
+1. **Implement caching:**
+```typescript
+class CacheManager {
+  private cache = new Map<string, { data: any; timestamp: number }>();
+  private ttl: number = 5000; // 5 seconds
+  
+  async getOrFetch<T>(
+    key: string,
+    fetcher: () => Promise<T>
+  ): Promise<T> {
+    const cached = this.cache.get(key);
+    
+    if (cached && Date.now() - cached.timestamp < this.ttl) {
+      return cached.data;
+    }
+    
+    const data = await fetcher();
+    this.cache.set(key, { data, timestamp: Date.now() });
+    
+    return data;
+  }
+}
+
+// Usage
+const cache = new CacheManager();
+const price = await cache.getOrFetch(
+  `price:${asset}`,
+  () => client.priceOracle.getPrice(asset)
+);
+```
+
+2. **Batch requests:**
+```typescript
+// Instead of multiple individual calls
+const positions = [];
+for (const id of positionIds) {
+  positions.push(await client.positionManager.getPosition(id));
+}
+
+// Use multicall or batch requests
+const multicall = new Multicall({ provider });
+const calls = positionIds.map(id => ({
+  target: positionManagerAddress,
+  callData: positionManager.interface.encodeFunctionData('getPosition', [id])
+}));
+
+const results = await multicall.aggregate(calls);
+```
+
+### Issue: "Memory leaks"
+
+**Solutions:**
+
+```typescript
+// Properly clean up event listeners
+class ComponentWithCleanup {
+  private listeners: Array<() => void> = [];
+  
+  initialize() {
+    const unsubscribe = client.positionManager.on('PositionOpened', 
+      this.handlePositionOpened
+    );
+    this.listeners.push(unsubscribe);
+  }
+  
+  cleanup() {
+    // Remove all listeners
+    this.listeners.forEach(unsub => unsub());
+    this.listeners = [];
+  }
+}
+```
+
+## Debugging Tools
+
+### 1. Enable Debug Logging
+
+```typescript
+// Set debug environment variable
+process.env.DEBUG = 'ethers:*,alpha-futures:*';
+
+// Custom logger
+class DebugLogger {
+  private enabled: boolean;
+  
+  constructor() {
+    this.enabled = process.env.NODE_ENV === 'development';
+  }
+  
+  log(category: string, message: string, data?: any) {
+    if (!this.enabled) return;
+    
+    console.log(`[${new Date().toISOString()}] [${category}] ${message}`, data);
+  }
+  
+  error(category: string, error: Error) {
+    console.error(`[${new Date().toISOString()}] [${category}]`, error);
+  }
+}
+```
+
+### 2. Transaction Debugger
+
+```typescript
+class TransactionDebugger {
+  async debugTransaction(txHash: string) {
+    const tx = await provider.getTransaction(txHash);
+    const receipt = await provider.getTransactionReceipt(txHash);
+    
+    console.log('Transaction:', {
+      hash: tx.hash,
+      from: tx.from,
+      to: tx.to,
+      value: ethers.formatEther(tx.value),
+      gasLimit: tx.gasLimit.toString(),
+      gasPrice: ethers.formatUnits(tx.gasPrice, 'gwei'),
+      nonce: tx.nonce,
+      data: tx.data
+    });
+    
+    console.log('Receipt:', {
+      status: receipt.status,
+      gasUsed: receipt.gasUsed.toString(),
+      effectiveGasPrice: ethers.formatUnits(receipt.effectiveGasPrice, 'gwei'),
+      logs: receipt.logs.length,
+      blockNumber: receipt.blockNumber
+    });
+    
+    // Decode logs
+    receipt.logs.forEach((log, i) => {
+      try {
+        const parsed = client.positionManager.interface.parseLog(log);
+        console.log(`Event ${i}:`, parsed.name, parsed.args);
+      } catch (e) {
+        // Not from this contract
+      }
+    });
+  }
+}
+```
+
+### 3. Network Monitor
+
+```typescript
+class NetworkMonitor {
+  private provider: Provider;
+  private lastBlock: number = 0;
+  private lastResponseTime: number = 0;
+  
+  constructor(provider: Provider) {
+    this.provider = provider;
+    this.startMonitoring();
+  }
+  
+  private async startMonitoring() {
+    setInterval(async () => {
+      const start = Date.now();
+      
+      try {
+        const block = await this.provider.getBlockNumber();
+        const responseTime = Date.now() - start;
+        
+        if (block > this.lastBlock) {
+          console.log(`New block: ${block} (${responseTime}ms)`);
+        }
+        
+        if (responseTime > 5000) {
+          console.warn(`Slow network response: ${responseTime}ms`);
+        }
+        
+        this.lastBlock = block;
+        this.lastResponseTime = responseTime;
+      } catch (error) {
+        console.error('Network monitor error:', error);
+      }
+    }, 5000);
+  }
+}
+```
+
+## FAQ
+
+### Q: How do I test on testnet?
+
+```typescript
+// Use testnet configuration
+const client = new AlphaFuturesClient({
+  rpcUrl: 'https://testnet-rpc.bittensor.com',
+  privateKey: process.env.TESTNET_PRIVATE_KEY,
+  network: 'testnet'
+});
+
+// Get testnet TAO from faucet
+async function requestTestnetFunds(address: string) {
+  const response = await fetch('https://faucet.bittensor.com', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ address })
+  });
+  
+  if (!response.ok) {
+    throw new Error('Faucet request failed');
+  }
+}
+```
+
+### Q: How do I handle different error types?
+
+```typescript
+import { 
+  ContractError, 
+  NetworkError, 
+  ValidationError 
+} from '@alpha-futures/sdk';
+
+try {
+  await client.positionManager.openPosition(params);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // Handle validation errors
+    alert(`Invalid input: ${error.field} - ${error.message}`);
+  } else if (error instanceof ContractError) {
+    // Handle contract errors
+    if (error.reason?.includes('Insufficient margin')) {
+      alert('Please deposit more margin');
+    } else {
+      alert(`Contract error: ${error.reason}`);
+    }
+  } else if (error instanceof NetworkError) {
+    // Handle network errors
+    alert('Network error. Please check your connection');
+  } else {
+    // Unknown error
+    console.error('Unknown error:', error);
+    alert('An unexpected error occurred');
+  }
+}
+```
+
+### Q: How do I optimize for mobile?
+
+```typescript
+// Mobile-optimized client
+class MobileOptimizedClient extends AlphaFuturesClient {
+  constructor(config: ClientConfig) {
+    super(config);
+    
+    // Reduce polling frequency
+    this.pollingInterval = 10000; // 10 seconds
+    
+    // Enable request batching
+    this.enableBatching = true;
+    
+    // Limit concurrent requests
+    this.maxConcurrentRequests = 2;
+  }
+  
+  // Override methods to add mobile-specific optimizations
+  async getPrice(asset: string): Promise<bigint> {
+    // Cache prices more aggressively on mobile
+    return this.withCache(`price:${asset}`, 30000, () => 
+      super.priceOracle.getPrice(asset)
+    );
+  }
+}
+```
+
+### Q: How do I implement a kill switch?
+
+```typescript
+class EmergencyManager {
+  private killSwitch: boolean = false;
+  
+  async checkKillSwitch(): Promise<void> {
+    // Check on-chain kill switch
+    const isEmergency = await client.protocolVault.isEmergencyMode();
+    
+    if (isEmergency) {
+      this.killSwitch = true;
+      throw new Error('Protocol is in emergency mode');
+    }
+  }
+  
+  wrapCall<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.killSwitch) {
+      throw new Error('Operations disabled due to emergency');
+    }
+    
+    return operation();
+  }
+}
+```
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Check the documentation**: Review the [API Reference](./API.md) and [Integration Guide](./INTEGRATION_GUIDE.md)
+
+2. **Search existing issues**: Check the [GitHub Issues](https://github.com/alpha-futures/sdk/issues)
+
+3. **Join the community**: 
+   - Discord: https://discord.gg/alphafutures
+   - Telegram: https://t.me/alphafutures
+
+4. **Report a bug**: Open an issue with:
+   - SDK version
+   - Error message and stack trace
+   - Minimal reproduction code
+   - Network and environment details
+
+5. **Contact support**: support@alphafutures.io