@megatao/sdk 1.1.0

package/src/utils/network.ts

@@ -0,0 +1,212 @@
+/**
+ * Network utilities for Alpha Futures SDK
+ */
+
+import { Chain, PublicClient, createPublicClient, http } from 'viem';
+import { mainnet, sepolia } from 'viem/chains';
+import { NetworkConfig } from '../types';
+import {
+  NETWORK_CONFIGS,
+  getCurrentNetwork,
+  getNetworkByChainId,
+  isValidNetwork,
+} from '../constants/networks';
+
+export interface NetworkInfo {
+  chainId: number;
+  name: string;
+  isSupported: boolean;
+  config?: NetworkConfig;
+}
+
+/**
+ * Create a custom chain configuration
+ */
+export function createCustomChain(config: NetworkConfig): Chain {
+  return {
+    id: config.chainId,
+    name: config.name,
+    nativeCurrency: {
+      decimals: 18,
+      name: 'TAO',
+      symbol: 'TAO',
+    },
+    rpcUrls: {
+      default: {
+        http: config.rpcUrl ? [config.rpcUrl] : [],
+      },
+    },
+    blockExplorers: config.blockExplorer
+      ? {
+          default: {
+            name: `${config.name} Explorer`,
+            url: config.blockExplorer,
+          },
+        }
+      : undefined,
+  };
+}
+
+/**
+ * Get chain configuration by ID
+ */
+export function getChainById(chainId: number): Chain {
+  switch (chainId) {
+    case 1:
+      return mainnet;
+    case 11155111:
+      return sepolia;
+    default: {
+      // Try to find in our configs
+      const config = getNetworkByChainId(chainId);
+      if (config) {
+        return createCustomChain(config);
+      }
+      // Return a basic chain config
+      return {
+        id: chainId,
+        name: `Chain ${chainId}`,
+        nativeCurrency: {
+          decimals: 18,
+          name: 'ETH',
+          symbol: 'ETH',
+        },
+        rpcUrls: {
+          default: { http: [] },
+        },
+      };
+    }
+  }
+}
+
+/**
+ * Detects the current network from a public client
+ */
+export async function detectNetwork(client: PublicClient): Promise<NetworkInfo> {
+  try {
+    const chainId = await client.getChainId();
+    const config = getNetworkByChainId(chainId);
+
+    return {
+      chainId,
+      name: config?.name || `Unknown (${chainId})`,
+      isSupported: !!config,
+      config,
+    };
+  } catch (error) {
+    throw new Error(`Failed to detect network: ${error}`);
+  }
+}
+
+/**
+ * Switches to a different network (for wallet providers like MetaMask)
+ */
+export async function switchNetwork(
+  provider: Record<string, unknown>, // EIP-1193 provider
+  targetNetwork: string,
+): Promise<void> {
+  if (!isValidNetwork(targetNetwork)) {
+    throw new Error(`Invalid network: ${targetNetwork}`);
+  }
+
+  const config = NETWORK_CONFIGS[targetNetwork];
+  const chainIdHex = `0x${config.chainId.toString(16)}`;
+
+  try {
+    // Try to switch to the network
+    await (provider as any).request({
+      method: 'wallet_switchEthereumChain',
+      params: [{ chainId: chainIdHex }],
+    });
+  } catch (error: unknown) {
+    // Network not added to wallet
+    if ((error as { code?: number }).code === 4902) {
+      await addNetwork(provider, targetNetwork);
+    } else {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Adds a network to the wallet
+ */
+export async function addNetwork(
+  provider: Record<string, unknown>, // EIP-1193 provider
+  networkName: string,
+): Promise<void> {
+  const config = NETWORK_CONFIGS[networkName];
+  if (!config) {
+    throw new Error(`Network configuration not found for: ${networkName}`);
+  }
+
+  const params = {
+    chainId: `0x${config.chainId.toString(16)}`,
+    chainName: config.name,
+    nativeCurrency: {
+      name: 'TAO',
+      symbol: 'TAO',
+      decimals: 18,
+    },
+    rpcUrls: config.rpcUrl ? [config.rpcUrl] : [],
+    blockExplorerUrls: config.blockExplorer ? [config.blockExplorer] : undefined,
+  };
+
+  await (provider as any).request({
+    method: 'wallet_addEthereumChain',
+    params: [params],
+  });
+}
+
+/**
+ * Creates a public client for a specific network
+ */
+export function createNetworkClient(networkName: string): PublicClient {
+  const config = NETWORK_CONFIGS[networkName];
+  if (!config || !config.rpcUrl) {
+    throw new Error(`Invalid network or missing RPC URL: ${networkName}`);
+  }
+
+  const chain = getChainById(config.chainId);
+
+  return createPublicClient({
+    chain,
+    transport: http(config.rpcUrl),
+  });
+}
+
+/**
+ * Validates chain ID matches expected network
+ */
+export async function validateChainId(
+  client: PublicClient,
+  expectedNetwork: string,
+): Promise<boolean> {
+  const config = NETWORK_CONFIGS[expectedNetwork];
+  if (!config) return false;
+
+  try {
+    const chainId = await client.getChainId();
+    return chainId === config.chainId;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get all supported networks
+ */
+export function getSupportedNetworks(): string[] {
+  return Object.keys(NETWORK_CONFIGS);
+}
+
+/**
+ * Format network name for display
+ */
+export function formatNetworkName(network: string): string {
+  const config = NETWORK_CONFIGS[network];
+  return config?.name || network;
+}
+
+// Re-export from constants for backward compatibility
+export { getCurrentNetwork, isValidNetwork, NETWORK_CONFIGS };

package/src/utils/positionCalculations.ts

@@ -0,0 +1,317 @@
+import { parseEther, formatEther } from 'viem';
+
+/**
+ * Position calculation utilities for Alpha Futures protocol
+ * Supports both collateral-first and size-first paradigms
+ * All calculations use 18 decimal precision (wei format in contracts)
+ */
+
+// ============================================================================
+// COLLATERAL-FIRST PARADIGM (NEW - Primary UX)
+// ============================================================================
+
+/**
+ * Calculate position size in tokens from collateral and leverage
+ * @param collateralUSD - Collateral amount in USD (as number, e.g., 100 for $100)
+ * @param leverage - Leverage multiplier (as number, e.g., 3.5 for 3.5x)
+ * @param tokenPriceUSD - Token price in USD (as number, e.g., 0.019)
+ * @returns Position size as bigint in wei (18 decimals)
+ * @example
+ * // $100 collateral, 3.5x leverage, $0.019 token price
+ * // = (100 * 3.5) / 0.019 = 18,421 tokens
+ * calculatePositionSizeFromCollateral(100, 3.5, 0.019)
+ * // Returns: 18421052631578947368421n (18421.05... * 1e18)
+ */
+export function calculatePositionSizeFromCollateral(
+  collateralUSD: number,
+  leverage: number,
+  tokenPriceUSD: number,
+): bigint {
+  if (tokenPriceUSD <= 0) {
+    throw new Error('Token price must be greater than 0');
+  }
+  if (leverage <= 0) {
+    throw new Error('Leverage must be greater than 0');
+  }
+  if (collateralUSD < 0) {
+    throw new Error('Collateral must be non-negative');
+  }
+
+  const positionSizeInTokens = (collateralUSD * leverage) / tokenPriceUSD;
+  return parseEther(positionSizeInTokens.toString());
+}
+
+/**
+ * Calculate position value in USD from collateral and leverage
+ * @param collateralUSD - Collateral amount in USD
+ * @param leverage - Leverage multiplier
+ * @returns Position value in USD
+ * @example
+ * // $100 collateral, 3.5x leverage
+ * calculatePositionValue(100, 3.5) // Returns: 350
+ */
+export function calculatePositionValue(collateralUSD: number, leverage: number): number {
+  if (leverage <= 0) {
+    throw new Error('Leverage must be greater than 0');
+  }
+  if (collateralUSD < 0) {
+    throw new Error('Collateral must be non-negative');
+  }
+
+  return collateralUSD * leverage;
+}
+
+// ============================================================================
+// SIZE-FIRST PARADIGM (OLD - Backward Compatibility)
+// ============================================================================
+
+/**
+ * Calculate required collateral from position size and leverage
+ * @param positionSizeUSD - Position size in USD
+ * @param leverage - Leverage multiplier
+ * @returns Required collateral in USD
+ * @example
+ * // $30 position size, 3x leverage
+ * // = 30 / 3 = $10 collateral required
+ * calculateCollateralFromSize(30, 3) // Returns: 10
+ */
+export function calculateCollateralFromSize(positionSizeUSD: number, leverage: number): number {
+  if (leverage <= 0) {
+    throw new Error('Leverage must be greater than 0');
+  }
+  if (positionSizeUSD < 0) {
+    throw new Error('Position size must be non-negative');
+  }
+
+  return positionSizeUSD / leverage;
+}
+
+/**
+ * Calculate leverage from position size and collateral
+ * @param positionSizeUSD - Position size in USD
+ * @param collateralUSD - Collateral amount in USD
+ * @returns Calculated leverage
+ * @example
+ * calculateLeverageFromSizeAndCollateral(30, 10) // Returns: 3
+ */
+export function calculateLeverageFromSizeAndCollateral(
+  positionSizeUSD: number,
+  collateralUSD: number,
+): number {
+  if (collateralUSD <= 0) {
+    throw new Error('Collateral must be greater than 0');
+  }
+  if (positionSizeUSD < 0) {
+    throw new Error('Position size must be non-negative');
+  }
+
+  return positionSizeUSD / collateralUSD;
+}
+
+// ============================================================================
+// CONVERSION UTILITIES
+// ============================================================================
+
+/**
+ * Convert USD amount to token amount using price
+ * @param amountUSD - Amount in USD
+ * @param tokenPriceUSD - Token price in USD
+ * @returns Token amount as bigint in wei
+ * @example
+ * // $100 USD at $0.019 per token
+ * usdToTokens(100, 0.019) // Returns: ~5263157894736842105263n (5263.16 * 1e18)
+ */
+export function usdToTokens(amountUSD: number, tokenPriceUSD: number): bigint {
+  if (tokenPriceUSD <= 0) {
+    throw new Error('Token price must be greater than 0');
+  }
+  if (amountUSD < 0) {
+    throw new Error('Amount must be non-negative');
+  }
+
+  const tokens = amountUSD / tokenPriceUSD;
+  return parseEther(tokens.toString());
+}
+
+/**
+ * Convert token amount to USD using price
+ * @param tokenAmount - Token amount as bigint in wei
+ * @param tokenPriceUSD - Token price in USD
+ * @returns Amount in USD
+ * @example
+ * // 1000 tokens at $0.019 per token
+ * tokensToUSD(parseEther('1000'), 0.019) // Returns: 19
+ */
+export function tokensToUSD(tokenAmount: bigint, tokenPriceUSD: number): number {
+  if (tokenPriceUSD < 0) {
+    throw new Error('Token price must be non-negative');
+  }
+
+  const tokens = parseFloat(formatEther(tokenAmount));
+  return tokens * tokenPriceUSD;
+}
+
+/**
+ * Convert leverage number to wei format (1e18 precision)
+ * @param leverage - Leverage as number (e.g., 3.5)
+ * @returns Leverage as bigint in wei (e.g., 3.5e18)
+ * @example
+ * leverageToWei(3.5) // Returns: 3500000000000000000n
+ */
+export function leverageToWei(leverage: number): bigint {
+  if (leverage < 0) {
+    throw new Error('Leverage must be non-negative');
+  }
+
+  return parseEther(leverage.toString());
+}
+
+/**
+ * Convert leverage wei format to number
+ * @param leverageWei - Leverage as bigint in wei
+ * @returns Leverage as number
+ * @example
+ * leverageFromWei(3500000000000000000n) // Returns: 3.5
+ */
+export function leverageFromWei(leverageWei: bigint): number {
+  return parseFloat(formatEther(leverageWei));
+}
+
+// ============================================================================
+// PROFIT/LOSS CALCULATIONS
+// ============================================================================
+
+/**
+ * Calculate P&L percentage from price movement and leverage
+ * @param priceChangePercent - Price change in percentage (e.g., 10 for +10%)
+ * @param leverage - Leverage multiplier
+ * @param isLong - True for long position, false for short
+ * @returns P&L percentage
+ * @example
+ * // Long position, 10x leverage, +10% price move
+ * calculatePnLPercent(10, 10, true) // Returns: 100 (100% gain)
+ *
+ * // Short position, 5x leverage, +10% price move
+ * calculatePnLPercent(10, 5, false) // Returns: -50 (50% loss)
+ */
+export function calculatePnLPercent(
+  priceChangePercent: number,
+  leverage: number,
+  isLong: boolean,
+): number {
+  if (leverage < 0) {
+    throw new Error('Leverage must be non-negative');
+  }
+
+  const direction = isLong ? 1 : -1;
+  return priceChangePercent * leverage * direction;
+}
+
+/**
+ * Calculate absolute P&L amount in USD from price movement
+ * @param collateralUSD - Collateral amount in USD
+ * @param leverage - Leverage multiplier
+ * @param priceChangePercent - Price change in percentage
+ * @param isLong - True for long position, false for short
+ * @returns P&L amount in USD
+ * @example
+ * // $100 collateral, 3x leverage, +10% price move, long
+ * calculatePnLAmount(100, 3, 10, true) // Returns: 30 (30% of $100)
+ */
+export function calculatePnLAmount(
+  collateralUSD: number,
+  leverage: number,
+  priceChangePercent: number,
+  isLong: boolean,
+): number {
+  if (leverage <= 0) {
+    throw new Error('Leverage must be greater than 0');
+  }
+  if (collateralUSD < 0) {
+    throw new Error('Collateral must be non-negative');
+  }
+
+  const pnlPercent = calculatePnLPercent(priceChangePercent, leverage, isLong);
+  return (collateralUSD * pnlPercent) / 100;
+}
+
+/**
+ * Calculate liquidation price from entry price and leverage
+ * @param entryPrice - Entry price of the position
+ * @param leverage - Leverage multiplier
+ * @param isLong - True for long position, false for short
+ * @param maintenanceMarginPercent - Maintenance margin percentage (default 20%)
+ * @returns Liquidation price
+ * @example
+ * // Long position at $100, 3x leverage, 20% maintenance margin
+ * // Liquidation at ~26.67% loss from entry (80% / 3)
+ * calculateLiquidationPriceFromLeverage(100, 3, true) // Returns: ~73.33
+ */
+export function calculateLiquidationPriceFromLeverage(
+  entryPrice: number,
+  leverage: number,
+  isLong: boolean,
+  maintenanceMarginPercent: number = 20,
+): number {
+  if (entryPrice <= 0) {
+    throw new Error('Entry price must be greater than 0');
+  }
+  if (leverage <= 0) {
+    throw new Error('Leverage must be greater than 0');
+  }
+  if (maintenanceMarginPercent < 0 || maintenanceMarginPercent >= 100) {
+    throw new Error('Maintenance margin must be between 0 and 100');
+  }
+
+  // Initial margin % = 100 / leverage
+  // Max loss before liquidation = (initial margin % - maintenance margin %)
+  // For long: liquidation = entry * (1 - maxLossPercent / 100)
+  // For short: liquidation = entry * (1 + maxLossPercent / 100)
+
+  const initialMarginPercent = 100 / leverage;
+  const maxLossPercent = initialMarginPercent - maintenanceMarginPercent;
+
+  if (isLong) {
+    return entryPrice * (1 - maxLossPercent / 100);
+  } else {
+    return entryPrice * (1 + maxLossPercent / 100);
+  }
+}
+
+/**
+ * Calculate required margin for a position size and leverage
+ * @param positionValueUSD - Position value in USD
+ * @param leverage - Leverage multiplier
+ * @returns Required margin in USD
+ * @example
+ * calculateRequiredMargin(350, 3.5) // Returns: 100
+ */
+export function calculateRequiredMargin(positionValueUSD: number, leverage: number): number {
+  if (leverage <= 0) {
+    throw new Error('Leverage must be greater than 0');
+  }
+  if (positionValueUSD < 0) {
+    throw new Error('Position value must be non-negative');
+  }
+
+  return positionValueUSD / leverage;
+}
+
+/**
+ * Calculate maximum position size from available collateral
+ * @param collateralUSD - Available collateral in USD
+ * @param leverage - Desired leverage
+ * @param tokenPriceUSD - Token price in USD
+ * @returns Maximum position size in tokens (as bigint in wei)
+ * @example
+ * // $100 collateral, 3x leverage, $0.019 token price
+ * calculateMaxPositionSize(100, 3, 0.019)
+ * // Returns: 15789473684210526315789n (~15789.47 tokens)
+ */
+export function calculateMaxPositionSize(
+  collateralUSD: number,
+  leverage: number,
+  tokenPriceUSD: number,
+): bigint {
+  return calculatePositionSizeFromCollateral(collateralUSD, leverage, tokenPriceUSD);
+}

package/src/utils/validation.ts

@@ -0,0 +1,76 @@
+/**
+ * Validation utilities
+ */
+
+import { isAddress } from 'viem';
+import { ValidationError } from '../errors';
+import { MIN_POSITION_SIZE, MAX_LEVERAGE, PRECISION } from '../constants';
+
+/**
+ * Validate Ethereum address
+ */
+export function validateAddress(address: string, fieldName: string = 'address'): void {
+  if (!isAddress(address)) {
+    throw new ValidationError(`Invalid Ethereum address: ${address}`, fieldName);
+  }
+}
+
+/**
+ * Validate position size
+ */
+export function validatePositionSize(size: bigint): void {
+  if (size < MIN_POSITION_SIZE) {
+    throw new ValidationError(
+      `Position size must be at least ${MIN_POSITION_SIZE / PRECISION} TAO`,
+      'size',
+    );
+  }
+}
+
+/**
+ * Validate leverage
+ */
+export function validateLeverage(leverage: bigint): void {
+  if (leverage < 1n || leverage > MAX_LEVERAGE) {
+    throw new ValidationError(`Leverage must be between 1 and ${MAX_LEVERAGE}`, 'leverage');
+  }
+}
+
+/**
+ * Validate positive amount
+ */
+export function validatePositiveAmount(amount: bigint, fieldName: string = 'amount'): void {
+  if (amount <= 0n) {
+    throw new ValidationError(`${fieldName} must be positive`, fieldName);
+  }
+}
+
+/**
+ * Validate asset symbol
+ */
+export function validateAsset(asset: string): void {
+  if (!asset || asset.trim().length === 0) {
+    throw new ValidationError('Asset symbol cannot be empty', 'asset');
+  }
+
+  // Basic validation for asset symbol format
+  const assetRegex = /^[A-Z0-9]{2,10}$/;
+  if (!assetRegex.test(asset)) {
+    throw new ValidationError(
+      'Asset symbol must be 2-10 uppercase alphanumeric characters',
+      'asset',
+    );
+  }
+}
+
+/**
+ * Validate margin amount
+ */
+export function validateMargin(margin: bigint, requiredMargin: bigint): void {
+  if (margin < requiredMargin) {
+    throw new ValidationError(
+      `Insufficient margin. Required: ${requiredMargin}, Provided: ${margin}`,
+      'margin',
+    );
+  }
+}