@megatao/sdk 1.1.0

package/dist/utils/positionCalculations.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculatePositionSizeFromCollateral = calculatePositionSizeFromCollateral;
+exports.calculatePositionValue = calculatePositionValue;
+exports.calculateCollateralFromSize = calculateCollateralFromSize;
+exports.calculateLeverageFromSizeAndCollateral = calculateLeverageFromSizeAndCollateral;
+exports.usdToTokens = usdToTokens;
+exports.tokensToUSD = tokensToUSD;
+exports.leverageToWei = leverageToWei;
+exports.leverageFromWei = leverageFromWei;
+exports.calculatePnLPercent = calculatePnLPercent;
+exports.calculatePnLAmount = calculatePnLAmount;
+exports.calculateLiquidationPriceFromLeverage = calculateLiquidationPriceFromLeverage;
+exports.calculateRequiredMargin = calculateRequiredMargin;
+exports.calculateMaxPositionSize = calculateMaxPositionSize;
+const viem_1 = require("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)
+ */
+function calculatePositionSizeFromCollateral(collateralUSD, leverage, tokenPriceUSD) {
+    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 (0, viem_1.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
+ */
+function calculatePositionValue(collateralUSD, leverage) {
+    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
+ */
+function calculateCollateralFromSize(positionSizeUSD, leverage) {
+    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
+ */
+function calculateLeverageFromSizeAndCollateral(positionSizeUSD, collateralUSD) {
+    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)
+ */
+function usdToTokens(amountUSD, tokenPriceUSD) {
+    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 (0, viem_1.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
+ */
+function tokensToUSD(tokenAmount, tokenPriceUSD) {
+    if (tokenPriceUSD < 0) {
+        throw new Error('Token price must be non-negative');
+    }
+    const tokens = parseFloat((0, viem_1.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
+ */
+function leverageToWei(leverage) {
+    if (leverage < 0) {
+        throw new Error('Leverage must be non-negative');
+    }
+    return (0, viem_1.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
+ */
+function leverageFromWei(leverageWei) {
+    return parseFloat((0, viem_1.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)
+ */
+function calculatePnLPercent(priceChangePercent, leverage, isLong) {
+    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)
+ */
+function calculatePnLAmount(collateralUSD, leverage, priceChangePercent, isLong) {
+    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
+ */
+function calculateLiquidationPriceFromLeverage(entryPrice, leverage, isLong, maintenanceMarginPercent = 20) {
+    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
+ */
+function calculateRequiredMargin(positionValueUSD, leverage) {
+    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)
+ */
+function calculateMaxPositionSize(collateralUSD, leverage, tokenPriceUSD) {
+    return calculatePositionSizeFromCollateral(collateralUSD, leverage, tokenPriceUSD);
+}
+//# sourceMappingURL=positionCalculations.js.map

package/dist/utils/positionCalculations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"positionCalculations.js","sourceRoot":"","sources":["../../src/utils/positionCalculations.ts"],"names":[],"mappings":"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"}

package/dist/utils/validation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Validation utilities
+ */
+/**
+ * Validate Ethereum address
+ */
+export declare function validateAddress(address: string, fieldName?: string): void;
+/**
+ * Validate position size
+ */
+export declare function validatePositionSize(size: bigint): void;
+/**
+ * Validate leverage
+ */
+export declare function validateLeverage(leverage: bigint): void;
+/**
+ * Validate positive amount
+ */
+export declare function validatePositiveAmount(amount: bigint, fieldName?: string): void;
+/**
+ * Validate asset symbol
+ */
+export declare function validateAsset(asset: string): void;
+/**
+ * Validate margin amount
+ */
+export declare function validateMargin(margin: bigint, requiredMargin: bigint): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAIpF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIvD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,MAAiB,GAAG,IAAI,CAIzF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAajD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAO3E"}

package/dist/utils/validation.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Validation utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAddress = validateAddress;
+exports.validatePositionSize = validatePositionSize;
+exports.validateLeverage = validateLeverage;
+exports.validatePositiveAmount = validatePositiveAmount;
+exports.validateAsset = validateAsset;
+exports.validateMargin = validateMargin;
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+const constants_1 = require("../constants");
+/**
+ * Validate Ethereum address
+ */
+function validateAddress(address, fieldName = 'address') {
+    if (!(0, viem_1.isAddress)(address)) {
+        throw new errors_1.ValidationError(`Invalid Ethereum address: ${address}`, fieldName);
+    }
+}
+/**
+ * Validate position size
+ */
+function validatePositionSize(size) {
+    if (size < constants_1.MIN_POSITION_SIZE) {
+        throw new errors_1.ValidationError(`Position size must be at least ${constants_1.MIN_POSITION_SIZE / constants_1.PRECISION} TAO`, 'size');
+    }
+}
+/**
+ * Validate leverage
+ */
+function validateLeverage(leverage) {
+    if (leverage < 1n || leverage > constants_1.MAX_LEVERAGE) {
+        throw new errors_1.ValidationError(`Leverage must be between 1 and ${constants_1.MAX_LEVERAGE}`, 'leverage');
+    }
+}
+/**
+ * Validate positive amount
+ */
+function validatePositiveAmount(amount, fieldName = 'amount') {
+    if (amount <= 0n) {
+        throw new errors_1.ValidationError(`${fieldName} must be positive`, fieldName);
+    }
+}
+/**
+ * Validate asset symbol
+ */
+function validateAsset(asset) {
+    if (!asset || asset.trim().length === 0) {
+        throw new errors_1.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 errors_1.ValidationError('Asset symbol must be 2-10 uppercase alphanumeric characters', 'asset');
+    }
+}
+/**
+ * Validate margin amount
+ */
+function validateMargin(margin, requiredMargin) {
+    if (margin < requiredMargin) {
+        throw new errors_1.ValidationError(`Insufficient margin. Required: ${requiredMargin}, Provided: ${margin}`, 'margin');
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":";AAAA;;GAEG;;AASH,0CAIC;AAKD,oDAOC;AAKD,4CAIC;AAKD,wDAIC;AAKD,sCAaC;AAKD,wCAOC;AAvED,+BAAiC;AACjC,sCAA4C;AAC5C,4CAA0E;AAE1E;;GAEG;AACH,SAAgB,eAAe,CAAC,OAAe,EAAE,YAAoB,SAAS;IAC5E,IAAI,CAAC,IAAA,gBAAS,EAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,wBAAe,CAAC,6BAA6B,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB,CAAC,IAAY;IAC/C,IAAI,IAAI,GAAG,6BAAiB,EAAE,CAAC;QAC7B,MAAM,IAAI,wBAAe,CACvB,kCAAkC,6BAAiB,GAAG,qBAAS,MAAM,EACrE,MAAM,CACP,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,QAAgB;IAC/C,IAAI,QAAQ,GAAG,EAAE,IAAI,QAAQ,GAAG,wBAAY,EAAE,CAAC;QAC7C,MAAM,IAAI,wBAAe,CAAC,kCAAkC,wBAAY,EAAE,EAAE,UAAU,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB,CAAC,MAAc,EAAE,YAAoB,QAAQ;IACjF,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,wBAAe,CAAC,GAAG,SAAS,mBAAmB,EAAE,SAAS,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,wBAAe,CAAC,8BAA8B,EAAE,OAAO,CAAC,CAAC;IACrE,CAAC;IAED,2CAA2C;IAC3C,MAAM,UAAU,GAAG,kBAAkB,CAAC;IACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,wBAAe,CACvB,6DAA6D,EAC7D,OAAO,CACR,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,MAAc,EAAE,cAAsB;IACnE,IAAI,MAAM,GAAG,cAAc,EAAE,CAAC;QAC5B,MAAM,IAAI,wBAAe,CACvB,kCAAkC,cAAc,eAAe,MAAM,EAAE,EACvE,QAAQ,CACT,CAAC;IACJ,CAAC;AACH,CAAC"}

package/docs/README.md

@@ -0,0 +1,40 @@
+# Alpha Futures SDK Documentation
+
+Welcome to the Alpha Futures SDK documentation. This directory contains comprehensive guides, references, and integration documentation for working with the Alpha Futures protocol.
+
+## Documentation Structure
+
+### 📘 [API Reference](./api/)
+- [API.md](./api/API.md) - Complete API reference for the Alpha Futures SDK
+
+### 📚 [Guides](./guides/)
+- [GETTING_STARTED.md](./guides/GETTING_STARTED.md) - Quick start guide for new users
+- [TRADING_GUIDE.md](./guides/TRADING_GUIDE.md) - Comprehensive trading guide with examples
+
+### 🔧 [Integration](./integration/)
+- [INTEGRATION_GUIDE.md](./integration/INTEGRATION_GUIDE.md) - SDK integration guide for developers
+- [VIEM_INTEGRATION.md](./integration/VIEM_INTEGRATION.md) - Guide for integrating with viem library
+
+### 📋 [Reference](./reference/)
+- [CLI_QUICK_REFERENCE.md](./reference/CLI_QUICK_REFERENCE.md) - Quick reference for CLI commands
+- [TROUBLESHOOTING.md](./reference/TROUBLESHOOTING.md) - Common issues and solutions
+
+## Quick Links
+
+### For Traders
+- Start with the [Getting Started Guide](./guides/GETTING_STARTED.md)
+- Learn advanced trading strategies in the [Trading Guide](./guides/TRADING_GUIDE.md)
+- Reference CLI commands in the [CLI Quick Reference](./reference/CLI_QUICK_REFERENCE.md)
+
+### For Developers
+- Integrate the SDK using the [Integration Guide](./integration/INTEGRATION_GUIDE.md)
+- Use viem with the [Viem Integration Guide](./integration/VIEM_INTEGRATION.md)
+- Explore the complete [API Reference](./api/API.md)
+
+### Need Help?
+- Check the [Troubleshooting Guide](./reference/TROUBLESHOOTING.md) for common issues
+- Visit our [GitHub repository](https://github.com/alpha-futures/sdk) for support
+
+## Contributing
+
+We welcome contributions to improve our documentation. Please submit pull requests or open issues on our GitHub repository.