@megatao/sdk 1.1.0

package/cli/utils/client.ts

@@ -0,0 +1,457 @@
+/**
+ * Client Utilities
+ *
+ * Helper functions for initializing and managing the Alpha Futures contracts
+ */
+
+import { localhost, mainnet, sepolia } from 'viem/chains';
+
+import type { Chain } from 'viem';
+import { AlphaFuturesClient, type AlphaClientConfig } from '../../src/AlphaFuturesClient';
+import type { Environment } from '../../src/config/environments';
+import { NETWORK_CONFIGS } from '../../src/constants/networks';
+import { SUBNET_MARKETS, getAssetAddress, isSubnetMarket } from '../../src/constants/assets';
+import chalk from 'chalk';
+import type { PublicClient } from 'viem';
+
+export interface ClientOptions {
+  network?: string;
+  rpc?: string;
+  key?: string;
+  privateKey?: string;
+}
+
+/**
+ * Initialize and return Alpha Futures client
+ */
+export async function getClient(options: ClientOptions): Promise<AlphaFuturesClient> {
+  const privateKey = options.key || options.privateKey || process.env.PRIVATE_KEY;
+  const rpcUrl = options.rpc;
+
+  // Auto-detect network: if custom RPC URL points to localhost, override to use 'localhost' network
+  // This ensures contract addresses are read from process.env instead of hardcoded production addresses
+  let network = options.network;
+  if (
+    rpcUrl &&
+    (rpcUrl.includes('localhost') ||
+      rpcUrl.includes('127.0.0.1') ||
+      rpcUrl.includes('::1') ||
+      rpcUrl.includes(':8545'))
+  ) {
+    network = 'localhost';
+  } else if (!network) {
+    network = 'localhost'; // Default to localhost for safety
+  }
+
+  // Get contract addresses for the network
+  const networkConfig = NETWORK_CONFIGS[network];
+  if (!networkConfig) {
+    throw new Error(`Network ${network} not found in configuration`);
+  }
+
+  // Get the chain based on network - use RPC from config
+  let chain: Chain;
+  switch (network) {
+    case 'mainnet':
+      chain = mainnet;
+      break;
+    case 'bittensor':
+      // Use RPC URL from network config
+      chain = {
+        id: networkConfig.chainId,
+        name: networkConfig.name,
+        nativeCurrency: {
+          decimals: 18,
+          name: 'TAO',
+          symbol: 'TAO',
+        },
+        rpcUrls: {
+          default: {
+            http: [
+              rpcUrl || networkConfig.rpcUrl || 'https://bittensor-finney.api.onfinality.io/public',
+            ],
+          },
+        },
+        blockExplorers: {
+          default: {
+            name: 'Bittensor Explorer',
+            url: networkConfig.blockExplorer || 'https://evm.taostats.io',
+          },
+        },
+      };
+      break;
+    case 'sepolia':
+      chain = sepolia;
+      break;
+    case 'localhost':
+    default:
+      // Use custom localhost/anvil chain configuration
+      chain = {
+        id: 31337,
+        name: 'Localhost',
+        nativeCurrency: {
+          decimals: 18,
+          name: 'Ether',
+          symbol: 'ETH',
+        },
+        rpcUrls: {
+          default: { http: [rpcUrl || networkConfig.rpcUrl || 'http://127.0.0.1:8545'] },
+        },
+      };
+      break;
+  }
+
+  const config: AlphaClientConfig = {
+    rpcUrl: rpcUrl || chain.rpcUrls.default.http[0],
+    privateKey: privateKey as `0x${string}` | undefined,
+  };
+
+  try {
+    // Map network string to Environment type
+    const environment = network as Environment;
+    return new AlphaFuturesClient(environment, config);
+  } catch (error: any) {
+    throw new Error(`Failed to initialize client: ${error.message}`);
+  }
+}
+
+/**
+ * Validates if a string is a valid Ethereum address
+ */
+function isValidAddress(address: string): boolean {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+
+/**
+ * Get asset mapping for supported subnet markets
+ */
+export function getAssetMapping(): Record<string, `0x${string}`> {
+  const mapping: Record<string, `0x${string}`> = {};
+
+  // Map all subnet markets
+  Object.entries(SUBNET_MARKETS).forEach(([symbol, market]) => {
+    mapping[symbol] = market.marketAddress;
+  });
+
+  return mapping;
+}
+
+/**
+ * Get market address for an asset symbol using subnet markets configuration
+ * Also supports BTC/ETH from environment variables for localhost testing
+ */
+export function getMarketAddress(asset: string): `0x${string}` {
+  const normalizedAsset = asset.toUpperCase();
+
+  // Check if it's a supported subnet market
+  if (isSubnetMarket(normalizedAsset)) {
+    return SUBNET_MARKETS[normalizedAsset].marketAddress;
+  }
+
+  // Check for test assets from environment variables (localhost/anvil testing)
+  const testAssetEnvMap: Record<string, string> = {
+    BTC: 'ALPHA_BTC',
+    ETH: 'ALPHA_ETH',
+  };
+
+  if (testAssetEnvMap[normalizedAsset]) {
+    const envVar = testAssetEnvMap[normalizedAsset];
+    const address = process.env[envVar];
+    if (address && /^0x[a-fA-F0-9]{40}$/.test(address)) {
+      return address as `0x${string}`;
+    }
+  }
+
+  // Check legacy assets
+  try {
+    return getAssetAddress(normalizedAsset);
+  } catch (error) {
+    // Asset not found
+    const availableMarkets = Object.keys(SUBNET_MARKETS).join(', ');
+
+    throw new Error(
+      `Market address not found for asset '${asset}'.\n` +
+        `Available subnet markets: ${availableMarkets}\n` +
+        `For localhost testing, BTC/ETH are available if ALPHA_BTC/ALPHA_ETH env vars are set.\n` +
+        `\n` +
+        `Supported assets are subnet markets only. Please use one of:\n` +
+        `  BITMIND (BitMind - SN34)\n` +
+        `  CHUTES (Chutes - SN64)\n` +
+        `  AFFINE (Affine - SN120)\n` +
+        `  RIDGES (Ridges - SN62)\n`,
+    );
+  }
+}
+
+/**
+ * List all available subnet market addresses
+ */
+export function listAvailableMarketAddresses(): Record<string, string> {
+  const markets: Record<string, string> = {};
+
+  // Get all subnet markets
+  Object.entries(SUBNET_MARKETS).forEach(([symbol, market]) => {
+    markets[symbol] = market.marketAddress;
+  });
+
+  return markets;
+}
+
+/**
+ * Validate that required subnet market addresses are available
+ */
+export function validateMarketAddresses(requiredAssets: string[] = ['BITMIND']): {
+  valid: boolean;
+  missing: string[];
+  available: Record<string, string>;
+} {
+  const missing: string[] = [];
+  const available = listAvailableMarketAddresses();
+
+  for (const asset of requiredAssets) {
+    if (!available[asset.toUpperCase()]) {
+      missing.push(asset);
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    available,
+  };
+}
+
+/**
+ * Resolve asset symbol to validated market address
+ */
+export function resolveAsset(asset?: string): string {
+  // Default to BitMind (first subnet market) if no asset specified
+  const targetAsset = asset || 'BITMIND';
+  const normalizedAsset = targetAsset.toUpperCase();
+
+  // Check if it's a supported subnet market
+  if (isSubnetMarket(normalizedAsset)) {
+    return normalizedAsset;
+  }
+
+  // Check for test assets from environment variables (localhost/anvil testing)
+  const testAssetEnvMap: Record<string, string> = {
+    BTC: 'ALPHA_BTC',
+    ETH: 'ALPHA_ETH',
+  };
+
+  if (testAssetEnvMap[normalizedAsset]) {
+    const envVar = testAssetEnvMap[normalizedAsset];
+    const address = process.env[envVar];
+    if (address && /^0x[a-fA-F0-9]{40}$/.test(address)) {
+      return normalizedAsset;
+    }
+  }
+
+  const availableMarkets = Object.keys(SUBNET_MARKETS).join(', ');
+  throw new Error(
+    `Unsupported asset '${targetAsset}'. Available subnet markets: ${availableMarkets}`,
+  );
+}
+
+/**
+ * Chunk large block ranges for event queries to prevent RPC timeouts
+ */
+export async function getEventsInChunks<T>(
+  publicClient: PublicClient,
+  getEventsConfig: {
+    address: `0x${string}`;
+    abi: any;
+    eventName: string;
+    args?: any;
+  },
+  fromBlock: bigint | 'earliest' = 'earliest',
+  toBlock: bigint | 'latest' = 'latest',
+  chunkSize: number = 5000,
+): Promise<T[]> {
+  // Get current block number if needed
+  const currentBlock = await publicClient.getBlockNumber();
+
+  // Convert 'earliest' and 'latest' to actual block numbers
+  let startBlock: bigint;
+  let endBlock: bigint;
+
+  if (fromBlock === 'earliest') {
+    startBlock = 0n;
+  } else {
+    startBlock = fromBlock;
+  }
+
+  if (toBlock === 'latest') {
+    endBlock = currentBlock;
+  } else {
+    endBlock = toBlock;
+  }
+
+  // If the range is small enough, query directly
+  const totalBlocks = Number(endBlock - startBlock);
+  if (totalBlocks <= chunkSize) {
+    return (await publicClient.getContractEvents({
+      ...getEventsConfig,
+      fromBlock: startBlock,
+      toBlock: endBlock,
+    })) as T[];
+  }
+
+  // Query in chunks
+  const allEvents: T[] = [];
+  const chunkSizeBigInt = BigInt(chunkSize);
+
+  for (let currentStart = startBlock; currentStart <= endBlock; currentStart += chunkSizeBigInt) {
+    const currentEnd =
+      currentStart + chunkSizeBigInt - 1n > endBlock
+        ? endBlock
+        : currentStart + chunkSizeBigInt - 1n;
+
+    try {
+      const events = (await publicClient.getContractEvents({
+        ...getEventsConfig,
+        fromBlock: currentStart,
+        toBlock: currentEnd,
+      })) as T[];
+
+      allEvents.push(...events);
+    } catch (error) {
+      console.warn(
+        `Warning: Failed to fetch events for blocks ${currentStart}-${currentEnd}:`,
+        error,
+      );
+      // Continue with remaining chunks
+    }
+  }
+
+  return allEvents;
+}
+
+/**
+ * Get recent events with a reasonable limit to prevent timeouts
+ */
+export async function getRecentEvents<T>(
+  publicClient: PublicClient,
+  getEventsConfig: {
+    address: `0x${string}`;
+    abi: any;
+    eventName: string;
+    args?: any;
+  },
+  maxBlocks: number = 10000,
+): Promise<T[]> {
+  const currentBlock = await publicClient.getBlockNumber();
+  const fromBlock = currentBlock > BigInt(maxBlocks) ? currentBlock - BigInt(maxBlocks) : 0n;
+
+  return getEventsInChunks<T>(
+    publicClient,
+    getEventsConfig,
+    fromBlock,
+    currentBlock,
+    5000, // 5k block chunks
+  );
+}
+
+/**
+ * Get events with optimized chunking for better performance
+ * Uses larger chunks initially and reduces on failures
+ */
+export async function getEventsOptimized<T>(
+  publicClient: PublicClient,
+  getEventsConfig: {
+    address: `0x${string}`;
+    abi: any;
+    eventName: string;
+    args?: any;
+  },
+  fromBlock: bigint | 'earliest' = 'earliest',
+  toBlock: bigint | 'latest' = 'latest',
+  limit?: number,
+): Promise<T[]> {
+  // For very large ranges, prefer recent events
+  if (fromBlock === 'earliest') {
+    const currentBlock = await publicClient.getBlockNumber();
+    const maxRecentBlocks = 50000; // Look back up to 50k blocks
+    fromBlock =
+      currentBlock > BigInt(maxRecentBlocks) ? currentBlock - BigInt(maxRecentBlocks) : 0n;
+  }
+
+  const events = await getEventsInChunks<T>(
+    publicClient,
+    getEventsConfig,
+    fromBlock,
+    toBlock,
+    10000, // 10k block chunks for better performance
+  );
+
+  // Apply limit if specified
+  if (limit && events.length > limit) {
+    return events.slice(-limit); // Get most recent
+  }
+
+  return events;
+}
+
+/**
+ * Handle errors with appropriate formatting
+ */
+export function handleError(error: any, options: any) {
+  if (options.json) {
+    console.error(
+      JSON.stringify(
+        {
+          error: true,
+          message: error.message || error.toString(),
+          code: error.code,
+          stack: options.debug ? error.stack : undefined,
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(chalk.red('\n❌ Error:'), error.message || error);
+
+    // Show additional error details
+    if (error.reason) {
+      console.error(chalk.gray('Reason:'), error.reason);
+    }
+    if (error.code) {
+      console.error(chalk.gray('Code:'), error.code);
+    }
+    if (error.transaction) {
+      console.error(chalk.gray('Transaction:'), error.transaction.hash);
+    }
+
+    // Show stack trace in debug mode
+    if (options.debug) {
+      console.error(chalk.gray('\nStack trace:'));
+      console.error(error.stack);
+    }
+
+    // Provide helpful suggestions based on error type
+    if (error.message?.includes('insufficient funds')) {
+      console.error(
+        chalk.yellow('\n💡 Tip: Check your account balance with "alpha-futures account balance"'),
+      );
+    } else if (error.message?.includes('nonce')) {
+      console.error(
+        chalk.yellow('\n💡 Tip: This might be a network issue. Try again in a moment.'),
+      );
+    } else if (error.message?.includes('gas')) {
+      console.error(
+        chalk.yellow(
+          '\n💡 Tip: The transaction may require more gas. Try increasing the gas limit.',
+        ),
+      );
+    } else if (error.message?.includes('revert')) {
+      console.error(
+        chalk.yellow('\n💡 Tip: The transaction was reverted. Check your inputs and try again.'),
+      );
+    }
+  }
+
+  // Exit with error code
+  process.exit(1);
+}

package/cli/utils/config.ts

@@ -0,0 +1,226 @@
+/**
+ * Configuration Utilities
+ *
+ * Helper functions for managing CLI configuration
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import chalk from 'chalk';
+import { getSupportedNetworks, isValidNetwork } from '../../src/constants/networks';
+
+export interface CliConfig {
+  network?: string;
+  rpcUrl?: string;
+  defaultAsset?: string;
+  defaultLeverage?: number;
+  confirmations?: boolean;
+  displayCurrency?: 'USD' | 'TAO';
+  theme?: 'default' | 'dark' | 'light';
+  gasPrice?: string;
+  gasLimit?: string;
+  slippage?: number;
+  [key: string]: any;
+}
+
+/**
+ * Get the config file path
+ */
+function getConfigPath(customPath?: string): string {
+  if (customPath) {
+    // Expand ~ to home directory
+    if (customPath.startsWith('~')) {
+      return path.join(os.homedir(), customPath.slice(1));
+    }
+    return customPath;
+  }
+
+  // Default path: ~/.alpha-futures/config.json
+  return path.join(os.homedir(), '.alpha-futures', 'config.json');
+}
+
+/**
+ * Load configuration from file
+ */
+export async function loadConfig(configPath?: string): Promise<CliConfig> {
+  const filePath = getConfigPath(configPath);
+
+  try {
+    const data = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(data);
+  } catch (error: any) {
+    // Return empty config if file doesn't exist
+    if (error.code === 'ENOENT') {
+      return {};
+    }
+
+    console.warn(chalk.yellow('Warning: Failed to load config:'), error.message);
+    return {};
+  }
+}
+
+/**
+ * Save configuration to file
+ */
+export async function saveConfig(configPath: string | undefined, config: CliConfig): Promise<void> {
+  const filePath = getConfigPath(configPath);
+
+  try {
+    // Ensure directory exists
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+
+    // Save config
+    await fs.writeFile(filePath, JSON.stringify(config, null, 2));
+  } catch (error: any) {
+    throw new Error(`Failed to save config: ${error.message}`);
+  }
+}
+
+/**
+ * Get a config value with fallback
+ */
+export function getConfigValue<T>(config: CliConfig, key: string, defaultValue: T): T {
+  return config[key] !== undefined ? config[key] : defaultValue;
+}
+
+/**
+ * Merge configurations with priority
+ */
+export function mergeConfigs(...configs: Partial<CliConfig>[]): CliConfig {
+  return configs.reduce((merged, config) => {
+    return { ...merged, ...config };
+  }, {} as CliConfig);
+}
+
+/**
+ * Validate configuration
+ */
+export function validateConfig(config: CliConfig): string[] {
+  const errors: string[] = [];
+
+  // Validate network
+  if (config.network) {
+    if (!isValidNetwork(config.network)) {
+      const validNetworks = getSupportedNetworks();
+      errors.push(
+        `Invalid network: ${config.network}. Must be one of: ${validNetworks.join(', ')}`,
+      );
+    }
+  }
+
+  // Validate RPC URL
+  if (config.rpcUrl) {
+    try {
+      new URL(config.rpcUrl);
+    } catch {
+      errors.push(`Invalid RPC URL: ${config.rpcUrl}`);
+    }
+  }
+
+  // Validate leverage
+  if (config.defaultLeverage !== undefined) {
+    if (config.defaultLeverage < 1 || config.defaultLeverage > 10) {
+      errors.push('Default leverage must be between 1 and 10');
+    }
+  }
+
+  // Validate slippage
+  if (config.slippage !== undefined) {
+    if (config.slippage < 0 || config.slippage > 50) {
+      errors.push('Slippage must be between 0 and 50 percent');
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Get default configuration
+ */
+export function getDefaultConfig(): CliConfig {
+  return {
+    network: 'localhost',
+    defaultAsset: 'ALPHA',
+    defaultLeverage: 3,
+    confirmations: true,
+    displayCurrency: 'USD',
+    theme: 'default',
+    slippage: 0.5,
+  };
+}
+
+/**
+ * Export configuration
+ */
+export async function exportConfig(config: CliConfig, outputPath: string): Promise<void> {
+  try {
+    await fs.writeFile(outputPath, JSON.stringify(config, null, 2));
+    console.log(chalk.green(`✓ Configuration exported to ${outputPath}`));
+  } catch (error: any) {
+    throw new Error(`Failed to export config: ${error.message}`);
+  }
+}
+
+/**
+ * Import configuration
+ */
+export async function importConfig(inputPath: string): Promise<CliConfig> {
+  try {
+    const data = await fs.readFile(inputPath, 'utf-8');
+    const config = JSON.parse(data);
+
+    // Validate imported config
+    const errors = validateConfig(config);
+    if (errors.length > 0) {
+      throw new Error(`Invalid configuration:\n${errors.join('\n')}`);
+    }
+
+    return config;
+  } catch (error: any) {
+    throw new Error(`Failed to import config: ${error.message}`);
+  }
+}
+
+/**
+ * Create a config preset
+ */
+export function createPreset(name: string): CliConfig {
+  const presets: Record<string, CliConfig> = {
+    conservative: {
+      defaultLeverage: 1,
+      confirmations: true,
+      slippage: 0.1,
+    },
+    moderate: {
+      defaultLeverage: 3,
+      confirmations: true,
+      slippage: 0.5,
+    },
+    aggressive: {
+      defaultLeverage: 5,
+      confirmations: false,
+      slippage: 1.0,
+    },
+    testnet: {
+      network: 'sepolia',
+      confirmations: true,
+      defaultLeverage: 3,
+    },
+    mainnet: {
+      network: 'bittensor',
+      confirmations: true,
+      defaultLeverage: 2,
+      slippage: 0.3,
+    },
+    bittensor: {
+      network: 'bittensor',
+      confirmations: true,
+      defaultLeverage: 3,
+      slippage: 0.5,
+    },
+  };
+
+  return presets[name] || getDefaultConfig();
+}