@megatao/sdk 1.1.0

package/docs/api/API.md

@@ -0,0 +1,831 @@
+# Alpha Futures SDK API Reference
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Client Initialization](#client-initialization)
+- [Margin Account Management](#margin-account-management)
+- [Position Management](#position-management)
+- [Price Oracle](#price-oracle)
+- [Funding Rates](#funding-rates)
+- [Liquidation](#liquidation)
+- [Protocol Vault](#protocol-vault)
+- [Utilities](#utilities)
+- [Types](#types)
+- [Error Handling](#error-handling)
+
+## Overview
+
+The Alpha Futures SDK provides a comprehensive TypeScript/JavaScript interface for interacting with the Alpha Futures perpetual futures protocol on Bittensor EVM.
+
+### Installation
+
+```bash
+npm install @alpha-futures/sdk
+```
+
+### Basic Usage
+
+```typescript
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+
+const client = new AlphaFuturesClient({
+  rpcUrl: 'https://your-rpc-url',
+  privateKey: 'your-private-key',
+  network: 'mainnet'
+});
+```
+
+## Client Initialization
+
+### AlphaFuturesClient
+
+The main entry point for interacting with the protocol.
+
+#### Constructor
+
+```typescript
+new AlphaFuturesClient(config: ClientConfig)
+```
+
+**Parameters:**
+- `config: ClientConfig` - Client configuration object
+
+**ClientConfig:**
+```typescript
+interface ClientConfig {
+  provider?: Provider;        // Ethers provider instance
+  signer?: Signer;           // Ethers signer instance
+  rpcUrl?: string;           // RPC URL (alternative to provider)
+  privateKey?: string;       // Private key (alternative to signer)
+  network?: string;          // Network name ('mainnet', 'testnet', 'localhost')
+  networkConfig?: NetworkConfig; // Custom network configuration
+}
+```
+
+**Example:**
+```typescript
+// Using RPC URL and private key
+const client = new AlphaFuturesClient({
+  rpcUrl: 'https://eth-mainnet.alchemyapi.io/v2/your-api-key',
+  privateKey: '0x...',
+  network: 'mainnet'
+});
+
+// Using existing provider and signer
+const provider = new ethers.JsonRpcProvider(rpcUrl);
+const signer = new ethers.Wallet(privateKey, provider);
+const client = new AlphaFuturesClient({
+  provider,
+  signer,
+  network: 'mainnet'
+});
+```
+
+## Margin Account Management
+
+### marginAccount.getMarginAccount()
+
+Get margin account information for a trader.
+
+```typescript
+async getMarginAccount(trader: string): Promise<MarginAccountInfo>
+```
+
+**Parameters:**
+- `trader: string` - Ethereum address of the trader
+
+**Returns:** `MarginAccountInfo`
+```typescript
+interface MarginAccountInfo {
+  user: string;             // Trader address
+  totalDeposited: bigint;   // Total TAO deposited
+  totalWithdrawn: bigint;   // Total TAO withdrawn
+  availableMargin: bigint;  // Available margin for new positions
+  usedMargin: bigint;       // Margin locked in positions
+  unrealizedPnL: bigint;    // Unrealized profit/loss
+  marginRatio: bigint;      // Current margin ratio in basis points
+}
+```
+
+### marginAccount.deposit()
+
+Deposit TAO as margin.
+
+```typescript
+async deposit(amount: bigint, options?: TransactionOptions): Promise<TransactionResponse>
+```
+
+**Parameters:**
+- `amount: bigint` - Amount of TAO to deposit (in wei)
+- `options?: TransactionOptions` - Optional transaction parameters
+
+**Example:**
+```typescript
+const amount = parseEther('1000'); // 1000 TAO (using viem)
+const tx = await client.marginAccount.deposit(amount);
+await tx.wait();
+```
+
+### marginAccount.withdraw()
+
+Withdraw available margin.
+
+```typescript
+async withdraw(amount: bigint, options?: TransactionOptions): Promise<TransactionResponse>
+```
+
+**Parameters:**
+- `amount: bigint` - Amount of TAO to withdraw (in wei)
+- `options?: TransactionOptions` - Optional transaction parameters
+
+### marginAccount.getTransactionHistory()
+
+Get deposit/withdrawal history.
+
+```typescript
+async getTransactionHistory(
+  trader: string,
+  fromBlock?: number,
+  toBlock?: number
+): Promise<TransactionHistory[]>
+```
+
+## Position Management
+
+### positionManager.openPosition()
+
+Open a new leveraged position.
+
+```typescript
+async openPosition(params: OpenPositionParams, options?: TransactionOptions): Promise<TransactionResponse>
+```
+
+**Parameters:**
+- `params: OpenPositionParams` - Position parameters
+- `options?: TransactionOptions` - Optional transaction parameters
+
+**OpenPositionParams:**
+```typescript
+interface OpenPositionParams {
+  asset: string;      // Asset symbol (e.g., 'ALPHA')
+  size: bigint;       // Position size in TAO (in wei)
+  leverage: number;   // Leverage (1-10)
+  isLong: boolean;    // true for long, false for short
+  slippage?: number;  // Max slippage in basis points
+  deadline?: number;  // Transaction deadline timestamp
+}
+```
+
+**Example:**
+```typescript
+const tx = await client.positionManager.openPosition({
+  asset: 'ALPHA',
+  size: ethers.parseEther('3000'),
+  leverage: 3,
+  isLong: true,
+  slippage: 50 // 0.5%
+});
+await tx.wait();
+```
+
+### positionManager.closePosition()
+
+Close an existing position.
+
+```typescript
+async closePosition(
+  positionId: bigint,
+  options?: TransactionOptions
+): Promise<TransactionResponse>
+```
+
+**Parameters:**
+- `positionId: bigint` - ID of the position to close
+- `options?: TransactionOptions` - Optional transaction parameters
+
+### positionManager.modifyPosition()
+
+Add or remove margin from a position.
+
+```typescript
+async modifyPosition(
+  positionId: bigint,
+  marginDelta: bigint,
+  isAdd: boolean,
+  options?: TransactionOptions
+): Promise<TransactionResponse>
+```
+
+**Parameters:**
+- `positionId: bigint` - ID of the position
+- `marginDelta: bigint` - Amount of margin to add/remove (in wei)
+- `isAdd: boolean` - true to add margin, false to remove
+- `options?: TransactionOptions` - Optional transaction parameters
+
+### positionManager.getPosition()
+
+Get details of a specific position.
+
+```typescript
+async getPosition(positionId: bigint): Promise<Position>
+```
+
+**Returns:** `Position`
+```typescript
+interface Position {
+  id: bigint;
+  trader: string;
+  asset: string;
+  size: bigint;
+  isLong: boolean;
+  leverage: bigint;
+  entryPrice: bigint;
+  margin: bigint;
+  lastFundingIndex: bigint;
+  openTimestamp: bigint;
+  unrealizedPnL?: bigint;
+  marginRatio?: bigint;
+  liquidationPrice?: bigint;
+}
+```
+
+### positionManager.getAllPositions()
+
+Get all positions for a trader.
+
+```typescript
+async getAllPositions(trader: string): Promise<Position[]>
+```
+
+### positionManager.getPositionsByAsset()
+
+Get all positions for a specific asset.
+
+```typescript
+async getPositionsByAsset(asset: string): Promise<Position[]>
+```
+
+## Price Oracle
+
+### priceOracle.getPrice()
+
+Get the current price of an asset.
+
+```typescript
+async getPrice(asset: string): Promise<bigint>
+```
+
+**Parameters:**
+- `asset: string` - Asset symbol
+
+**Returns:** Current price in wei (18 decimals)
+
+### priceOracle.getAllPrices()
+
+Get prices for all supported assets.
+
+```typescript
+async getAllPrices(): Promise<PriceInfo[]>
+```
+
+**Returns:** Array of `PriceInfo`
+```typescript
+interface PriceInfo {
+  asset: string;
+  price: bigint;
+  timestamp: number;
+  confidence?: bigint;  // Price confidence in basis points
+  source?: string;      // Price source identifier
+}
+```
+
+### priceOracle.isPriceFresh()
+
+Check if a price is fresh (not stale).
+
+```typescript
+async isPriceFresh(asset: string, maxAge: number): Promise<boolean>
+```
+
+**Parameters:**
+- `asset: string` - Asset symbol
+- `maxAge: number` - Maximum age in seconds
+
+## Funding Rates
+
+### fundingRate.getCurrentFundingRate()
+
+Get the current funding rate for an asset.
+
+```typescript
+async getCurrentFundingRate(asset: string): Promise<FundingRateInfo>
+```
+
+**Returns:** `FundingRateInfo`
+```typescript
+interface FundingRateInfo {
+  asset: string;
+  rate: bigint;              // Rate in basis points (always positive)
+  isPositive: boolean;       // true if longs pay shorts
+  nextUpdateTime: bigint;    // Next funding rate update timestamp
+  accumulatedIndex: bigint;  // Accumulated funding index
+}
+```
+
+### fundingRate.getAllFundingRates()
+
+Get funding rates for all assets.
+
+```typescript
+async getAllFundingRates(): Promise<FundingRateInfo[]>
+```
+
+### fundingRate.getAccumulatedFunding()
+
+Calculate accumulated funding between two indices.
+
+```typescript
+async getAccumulatedFunding(
+  asset: string,
+  startIndex: bigint,
+  endIndex: bigint
+): Promise<bigint>
+```
+
+### fundingRate.applyFunding()
+
+Apply funding to a specific position.
+
+```typescript
+async applyFunding(
+  positionId: bigint,
+  options?: TransactionOptions
+): Promise<TransactionResponse>
+```
+
+## Liquidation
+
+### liquidationEngine.checkLiquidationStatus()
+
+Check if a position can be liquidated.
+
+```typescript
+async checkLiquidationStatus(positionId: bigint): Promise<LiquidationStatus>
+```
+
+**Returns:** `LiquidationStatus`
+```typescript
+interface LiquidationStatus {
+  canLiquidate: boolean;
+  marginRatio: bigint;      // Current margin ratio in basis points
+  requiredMargin: bigint;   // Required maintenance margin
+  currentMargin: bigint;    // Current position margin
+  liquidationPrice: bigint; // Price at which position will be liquidated
+}
+```
+
+### liquidationEngine.liquidatePosition()
+
+Liquidate an underwater position.
+
+```typescript
+async liquidatePosition(
+  positionId: bigint,
+  options?: TransactionOptions
+): Promise<TransactionResponse>
+```
+
+### liquidationEngine.getAtRiskPositions()
+
+Get all positions at risk of liquidation.
+
+```typescript
+async getAtRiskPositions(threshold?: bigint): Promise<AtRiskPosition[]>
+```
+
+**Parameters:**
+- `threshold?: bigint` - Margin ratio threshold (default: 250 = 25%)
+
+**Returns:** Array of `AtRiskPosition`
+```typescript
+interface AtRiskPosition {
+  positionId: bigint;
+  marginRatio: bigint;
+  liquidationPrice: bigint;
+  trader: string;
+  asset: string;
+}
+```
+
+### liquidationEngine.getLiquidationHistory()
+
+Get liquidation history.
+
+```typescript
+async getLiquidationHistory(
+  fromBlock?: number,
+  toBlock?: number
+): Promise<LiquidationEvent[]>
+```
+
+## Protocol Vault
+
+### protocolVault.getVaultStats()
+
+Get protocol vault statistics.
+
+```typescript
+async getVaultStats(): Promise<VaultStats>
+```
+
+**Returns:** `VaultStats`
+```typescript
+interface VaultStats {
+  totalReserves: bigint;      // Total TAO in vault
+  totalBorrowed: bigint;      // TAO borrowed for positions
+  utilizationRate: bigint;    // Utilization in basis points
+  availableLiquidity: bigint; // Available for new positions
+  insuranceFund: bigint;      // Insurance fund balance
+  totalFees24h: bigint;       // Fees collected in last 24h
+  apy: bigint;                // Annual percentage yield in basis points
+}
+```
+
+### protocolVault.getVaultBalance()
+
+Get current vault balance.
+
+```typescript
+async getVaultBalance(): Promise<bigint>
+```
+
+### protocolVault.getVaultPerformance()
+
+Get vault performance metrics.
+
+```typescript
+async getVaultPerformance(): Promise<VaultPerformance>
+```
+
+**Returns:** `VaultPerformance`
+```typescript
+interface VaultPerformance {
+  totalFees: bigint;
+  totalLiquidations: bigint;
+  apy: bigint;
+  utilizationHistory: UtilizationPoint[];
+}
+```
+
+## Utilities
+
+### Calculation Utilities
+
+```typescript
+import { 
+  calculateInitialMargin,
+  calculateMaintenanceMargin,
+  calculateLeverage,
+  calculatePositionSize,
+  calculateUnrealizedPnL,
+  calculateMarginRatio,
+  calculateLiquidationPrice,
+  calculateTradingFee,
+  calculateFundingPayment,
+  calculatePriceImpact
+} from '@alpha-futures/sdk/utils';
+```
+
+#### calculateInitialMargin()
+```typescript
+function calculateInitialMargin(positionSize: bigint): bigint
+```
+Calculate required initial margin for a position size.
+
+#### calculateUnrealizedPnL()
+```typescript
+function calculateUnrealizedPnL(
+  isLong: boolean,
+  size: bigint,
+  entryPrice: bigint,
+  currentPrice: bigint
+): bigint
+```
+Calculate unrealized profit/loss for a position.
+
+#### calculateLiquidationPrice()
+```typescript
+function calculateLiquidationPrice(
+  isLong: boolean,
+  entryPrice: bigint,
+  margin: bigint,
+  positionSize: bigint
+): bigint
+```
+Calculate the liquidation price for a position.
+
+### Format Utilities
+
+```typescript
+import { 
+  formatAmount,
+  formatPrice,
+  formatPercentage,
+  formatLeverage,
+  parseAmount,
+  shortenAddress,
+  formatTimestamp
+} from '@alpha-futures/sdk/utils';
+```
+
+#### formatAmount()
+```typescript
+function formatAmount(amount: bigint, decimals?: number): string
+```
+Format TAO amount for display (e.g., "1,234.56").
+
+#### formatPrice()
+```typescript
+function formatPrice(price: bigint): string
+```
+Format price for display (e.g., "$123.45").
+
+#### formatPercentage()
+```typescript
+function formatPercentage(basisPoints: bigint, decimals?: number): string
+```
+Format basis points as percentage (e.g., "12.34%").
+
+### Validation Utilities
+
+```typescript
+import { 
+  validateAddress,
+  validatePositionSize,
+  validateLeverage,
+  validatePositiveAmount,
+  validateAsset,
+  validateMargin
+} from '@alpha-futures/sdk/utils';
+```
+
+All validation functions throw `ValidationError` on failure.
+
+## Types
+
+### Core Types
+
+```typescript
+// Position information
+interface Position {
+  id: bigint;
+  trader: string;
+  asset: string;
+  size: bigint;
+  isLong: boolean;
+  leverage: bigint;
+  entryPrice: bigint;
+  margin: bigint;
+  lastFundingIndex: bigint;
+  openTimestamp: bigint;
+  unrealizedPnL?: bigint;
+  marginRatio?: bigint;
+  liquidationPrice?: bigint;
+}
+
+// Transaction options
+interface TransactionOptions {
+  gasLimit?: bigint;
+  gasPrice?: bigint;
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+  nonce?: number;
+  value?: bigint;
+}
+
+// Network configuration
+interface NetworkConfig {
+  chainId: number;
+  name: string;
+  rpcUrl?: string;
+  contracts: {
+    marginAccount: string;
+    positionManager: string;
+    fundingRate: string;
+    liquidationEngine: string;
+    protocolVault: string;
+    priceOracle: string;
+    taoToken: string;
+    alphaFuturesOrderBook?: string;
+  };
+  blockExplorer?: string;
+}
+```
+
+## Error Handling
+
+The SDK provides custom error types for better error handling:
+
+### ValidationError
+
+Thrown when input validation fails.
+
+```typescript
+class ValidationError extends Error {
+  field: string;
+  value?: any;
+}
+```
+
+### ContractError
+
+Thrown when contract calls fail.
+
+```typescript
+class ContractError extends Error {
+  code: string;
+  reason?: string;
+}
+```
+
+### NetworkError
+
+Thrown on network-related issues.
+
+```typescript
+class NetworkError extends Error {
+  code: string;
+}
+```
+
+### Example Error Handling
+
+```typescript
+try {
+  await client.positionManager.openPosition({
+    asset: 'ALPHA',
+    size: ethers.parseEther('1000'),
+    leverage: 3,
+    isLong: true
+  });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error(`Validation failed for ${error.field}: ${error.message}`);
+  } else if (error instanceof ContractError) {
+    console.error(`Contract error: ${error.reason || error.message}`);
+  } else if (error instanceof NetworkError) {
+    console.error(`Network error: ${error.message}`);
+  } else {
+    console.error(`Unknown error: ${error.message}`);
+  }
+}
+```
+
+## Event Listening
+
+The SDK supports listening to protocol events:
+
+```typescript
+// Listen for position opened events
+client.positionManager.on('PositionOpened', (
+  positionId: bigint,
+  trader: string,
+  asset: string,
+  size: bigint,
+  isLong: boolean,
+  leverage: bigint
+) => {
+  console.log(`Position ${positionId} opened`);
+});
+
+// Listen for liquidation events
+client.liquidationEngine.on('PositionLiquidated', (
+  positionId: bigint,
+  liquidator: string,
+  remainingMargin: bigint,
+  liquidationBonus: bigint
+) => {
+  console.log(`Position ${positionId} liquidated`);
+});
+
+// Query historical events
+const events = await client.positionManager.queryFilter(
+  client.positionManager.filters.PositionOpened(null, traderAddress),
+  fromBlock,
+  toBlock
+);
+```
+
+## Gas Estimation
+
+The SDK provides gas estimation for all transactions:
+
+```typescript
+// Estimate gas before sending transaction
+const estimatedGas = await client.positionManager.estimateGas.openPosition({
+  asset: 'ALPHA',
+  size: ethers.parseEther('1000'),
+  leverage: 3,
+  isLong: true
+});
+
+// Use estimated gas with buffer
+const tx = await client.positionManager.openPosition(
+  {
+    asset: 'ALPHA',
+    size: ethers.parseEther('1000'),
+    leverage: 3,
+    isLong: true
+  },
+  {
+    gasLimit: estimatedGas * 120n / 100n // 20% buffer
+  }
+);
+```
+
+## Constants
+
+The SDK exports useful constants:
+
+```typescript
+import { 
+  PRECISION,              // 10^18
+  BASIS_POINTS,          // 10^4
+  MIN_POSITION_SIZE,     // Minimum position size
+  MAX_LEVERAGE,          // Maximum leverage (10x)
+  INITIAL_MARGIN_RATIO,  // Initial margin requirement (3333 = 33.33%)
+  MAINTENANCE_MARGIN_RATIO, // Maintenance margin (2000 = 20%)
+  LIQUIDATION_BONUS,     // Liquidation incentive (500 = 5%)
+  TRADING_FEE,           // Trading fee (10 = 0.1%)
+  SUPPORTED_ASSETS       // Array of supported asset symbols
+} from '@alpha-futures/sdk/constants';
+```
+
+## Advanced Usage
+
+### Custom Network Configuration
+
+```typescript
+const customConfig: NetworkConfig = {
+  chainId: 1337,
+  name: 'custom-network',
+  rpcUrl: 'http://localhost:8545',
+  contracts: {
+    marginAccount: '0x...',
+    positionManager: '0x...',
+    fundingRate: '0x...',
+    liquidationEngine: '0x...',
+    protocolVault: '0x...',
+    priceOracle: '0x...',
+    taoToken: '0x...'
+  }
+};
+
+const client = new AlphaFuturesClient({
+  rpcUrl: customConfig.rpcUrl,
+  privateKey: 'your-private-key',
+  networkConfig: customConfig
+});
+```
+
+### Batch Operations
+
+```typescript
+// Open multiple positions in sequence
+const positions = [
+  { asset: 'ALPHA', size: ethers.parseEther('1000'), leverage: 2, isLong: true },
+  { asset: 'BETA', size: ethers.parseEther('2000'), leverage: 3, isLong: false }
+];
+
+const txHashes = [];
+for (const pos of positions) {
+  const tx = await client.positionManager.openPosition(pos);
+  txHashes.push(tx.hash);
+  await tx.wait(); // Wait for confirmation
+}
+```
+
+### Error Recovery
+
+```typescript
+async function openPositionWithRetry(params: OpenPositionParams, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const tx = await client.positionManager.openPosition(params);
+      return await tx.wait();
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      
+      // Check if error is retryable
+      if (error.message.includes('nonce too low')) {
+        // Wait and retry
+        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+        continue;
+      }
+      
+      throw error; // Non-retryable error
+    }
+  }
+}
+```