@megatao/sdk 1.1.0

package/src/constants/assets.ts

@@ -0,0 +1,299 @@
+/**
+ * Asset mappings and constants for Alpha Futures
+ * Includes both legacy assets and new subnet markets
+ */
+
+import { Address } from 'viem';
+
+/**
+ * Subnet market configuration for trading
+ */
+export interface SubnetMarketAsset {
+  /** Subnet ID on the Bittensor network */
+  subnetId: number;
+  /** Human-readable name of the subnet */
+  name: string;
+  /** Market contract address for this subnet */
+  marketAddress: Address;
+  /** Symbol used for trading */
+  symbol: string;
+  /** Full display name */
+  displayName: string;
+  /** Asset decimals (typically 18 for subnet tokens) */
+  decimals: number;
+  /** Whether oracle pricing is currently available */
+  hasOraclePrice: boolean;
+}
+
+/**
+ * Bittensor subnet markets available for Alpha Futures trading
+ * Top 12 subnets by emission (as of 2025)
+ */
+export const SUBNET_MARKETS: Record<string, SubnetMarketAsset> = {
+  CHUTES: {
+    subnetId: 64,
+    name: 'Chutes',
+    marketAddress: '0x0000000000000000000000000000000000000040',
+    symbol: 'CHUTES',
+    displayName: 'Chutes (SN64)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  LIUM: {
+    subnetId: 51,
+    name: 'lium.io',
+    marketAddress: '0x0000000000000000000000000000000000000033',
+    symbol: 'LIUM',
+    displayName: 'lium.io (SN51)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  RIDGES: {
+    subnetId: 62,
+    name: 'Ridges',
+    marketAddress: '0x000000000000000000000000000000000000003e',
+    symbol: 'RIDGES',
+    displayName: 'Ridges (SN62)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  TARGON: {
+    subnetId: 4,
+    name: 'Targon',
+    marketAddress: '0x0000000000000000000000000000000000000004',
+    symbol: 'TARGON',
+    displayName: 'Targon (SN4)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  VANTA: {
+    subnetId: 8,
+    name: 'Vanta',
+    marketAddress: '0x0000000000000000000000000000000000000008',
+    symbol: 'VANTA',
+    displayName: 'Vanta (SN8)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  AFFINE: {
+    subnetId: 120,
+    name: 'Affine',
+    marketAddress: '0x0000000000000000000000000000000000000078',
+    symbol: 'AFFINE',
+    displayName: 'Affine (SN120)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  TEMPLAR: {
+    subnetId: 3,
+    name: 'templar',
+    marketAddress: '0x0000000000000000000000000000000000000003',
+    symbol: 'TEMPLAR',
+    displayName: 'templar (SN3)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  SCORE: {
+    subnetId: 44,
+    name: 'Score',
+    marketAddress: '0x000000000000000000000000000000000000002c',
+    symbol: 'SCORE',
+    displayName: 'Score (SN44)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  IOTA: {
+    subnetId: 9,
+    name: 'iota',
+    marketAddress: '0x0000000000000000000000000000000000000009',
+    symbol: 'IOTA',
+    displayName: 'iota (SN9)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  GRADIENTS: {
+    subnetId: 56,
+    name: 'Gradients',
+    marketAddress: '0x0000000000000000000000000000000000000038',
+    symbol: 'GRADIENTS',
+    displayName: 'Gradients (SN56)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  HIPPIUS: {
+    subnetId: 75,
+    name: 'Hippius',
+    marketAddress: '0x000000000000000000000000000000000000004b',
+    symbol: 'HIPPIUS',
+    displayName: 'Hippius (SN75)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  BITMIND: {
+    subnetId: 34,
+    name: 'BitMind',
+    marketAddress: '0x0000000000000000000000000000000000000022',
+    symbol: 'BITMIND',
+    displayName: 'BitMind (SN34)',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+  MTSOS: {
+    subnetId: 65534,
+    name: 'MTSOS',
+    marketAddress: '0x000000000000000000000000000000000000FFFE',
+    symbol: 'MTSOS',
+    displayName: 'MegaTAO Sum-of-Subnets Index',
+    decimals: 18,
+    hasOraclePrice: true,
+  },
+} as const;
+
+/**
+ * Legacy asset addresses (maintained for backward compatibility)
+ */
+export const ASSET_ADDRESSES: Record<string, Address> = {
+  // Legacy assets
+  ALPHA: '0x0000000000000000000000000000000000000001',
+  TAO: '0x0000000000000000000000000000000000000002',
+  // Subnet market addresses
+  CHUTES: SUBNET_MARKETS.CHUTES.marketAddress,
+  LIUM: SUBNET_MARKETS.LIUM.marketAddress,
+  RIDGES: SUBNET_MARKETS.RIDGES.marketAddress,
+  TARGON: SUBNET_MARKETS.TARGON.marketAddress,
+  VANTA: SUBNET_MARKETS.VANTA.marketAddress,
+  AFFINE: SUBNET_MARKETS.AFFINE.marketAddress,
+  TEMPLAR: SUBNET_MARKETS.TEMPLAR.marketAddress,
+  SCORE: SUBNET_MARKETS.SCORE.marketAddress,
+  IOTA: SUBNET_MARKETS.IOTA.marketAddress,
+  GRADIENTS: SUBNET_MARKETS.GRADIENTS.marketAddress,
+  HIPPIUS: SUBNET_MARKETS.HIPPIUS.marketAddress,
+  BITMIND: SUBNET_MARKETS.BITMIND.marketAddress,
+  MTSOS: SUBNET_MARKETS.MTSOS.marketAddress,
+} as const;
+
+export const ASSET_NAMES: Record<Address, string> = {
+  '0x0000000000000000000000000000000000000001': 'ALPHA',
+  '0x0000000000000000000000000000000000000002': 'TAO',
+  // Subnet market names
+  [SUBNET_MARKETS.CHUTES.marketAddress]: 'CHUTES',
+  [SUBNET_MARKETS.LIUM.marketAddress]: 'LIUM',
+  [SUBNET_MARKETS.RIDGES.marketAddress]: 'RIDGES',
+  [SUBNET_MARKETS.TARGON.marketAddress]: 'TARGON',
+  [SUBNET_MARKETS.VANTA.marketAddress]: 'VANTA',
+  [SUBNET_MARKETS.AFFINE.marketAddress]: 'AFFINE',
+  [SUBNET_MARKETS.TEMPLAR.marketAddress]: 'TEMPLAR',
+  [SUBNET_MARKETS.SCORE.marketAddress]: 'SCORE',
+  [SUBNET_MARKETS.IOTA.marketAddress]: 'IOTA',
+  [SUBNET_MARKETS.GRADIENTS.marketAddress]: 'GRADIENTS',
+  [SUBNET_MARKETS.HIPPIUS.marketAddress]: 'HIPPIUS',
+  [SUBNET_MARKETS.BITMIND.marketAddress]: 'BITMIND',
+  [SUBNET_MARKETS.MTSOS.marketAddress]: 'MTSOS',
+} as const;
+
+export const ASSET_DECIMALS: Record<string, number> = {
+  // Legacy assets
+  ALPHA: 18,
+  TAO: 18,
+  // Subnet markets (all use 18 decimals)
+  CHUTES: 18,
+  LIUM: 18,
+  RIDGES: 18,
+  TARGON: 18,
+  VANTA: 18,
+  AFFINE: 18,
+  TEMPLAR: 18,
+  SCORE: 18,
+  IOTA: 18,
+  GRADIENTS: 18,
+  HIPPIUS: 18,
+  BITMIND: 18,
+  MTSOS: 18,
+} as const;
+
+/**
+ * Convert asset symbol to address
+ */
+export function getAssetAddress(symbol: string): Address {
+  const address = ASSET_ADDRESSES[symbol.toUpperCase()];
+  if (!address) {
+    throw new Error(`Unknown asset symbol: ${symbol}`);
+  }
+  return address;
+}
+
+/**
+ * Convert asset address to symbol
+ */
+export function getAssetSymbol(address: Address): string {
+  const symbol = ASSET_NAMES[address];
+  if (!symbol) {
+    throw new Error(`Unknown asset address: ${address}`);
+  }
+  return symbol;
+}
+
+/**
+ * Check if asset is supported
+ */
+export function isAssetSupported(symbolOrAddress: string): boolean {
+  const symbol = symbolOrAddress.toUpperCase();
+  return symbol in ASSET_ADDRESSES || symbolOrAddress in ASSET_NAMES;
+}
+
+/**
+ * Get asset decimals
+ */
+export function getAssetDecimals(symbol: string): number {
+  const decimals = ASSET_DECIMALS[symbol.toUpperCase()];
+  if (decimals === undefined) {
+    throw new Error(`Unknown asset symbol: ${symbol}`);
+  }
+  return decimals;
+}
+
+/**
+ * Get subnet market by symbol
+ */
+export function getSubnetMarket(symbol: string): SubnetMarketAsset {
+  const market = SUBNET_MARKETS[symbol.toUpperCase()];
+  if (!market) {
+    throw new Error(`Unknown subnet market symbol: ${symbol}`);
+  }
+  return market;
+}
+
+/**
+ * Get all available subnet markets
+ */
+export function getAvailableSubnetMarkets(): SubnetMarketAsset[] {
+  return Object.values(SUBNET_MARKETS);
+}
+
+/**
+ * Check if symbol is a subnet market
+ */
+export function isSubnetMarket(symbol: string): boolean {
+  return symbol.toUpperCase() in SUBNET_MARKETS;
+}
+
+/**
+ * Get subnet market by subnet ID
+ */
+export function getSubnetMarketById(subnetId: number): SubnetMarketAsset | undefined {
+  return Object.values(SUBNET_MARKETS).find((market) => market.subnetId === subnetId);
+}
+
+/**
+ * List all supported assets (legacy + subnet markets)
+ */
+export function getSupportedAssets(): string[] {
+  return Object.keys(ASSET_ADDRESSES);
+}
+
+/**
+ * List only subnet market symbols
+ */
+export function getSupportedSubnetMarkets(): string[] {
+  return Object.keys(SUBNET_MARKETS);
+}

package/src/constants/contracts.ts

@@ -0,0 +1,64 @@
+/**
+ * Contract-related constants
+ */
+
+// Contract method signatures
+export const CONTRACT_METHODS = {
+  // MarginAccount
+  DEPOSIT: 'deposit',
+  WITHDRAW: 'withdraw',
+  GET_BALANCE: 'getBalance',
+  GET_AVAILABLE_BALANCE: 'getAvailableBalance',
+
+  // Position Management
+  OPEN_MARKET_POSITION: 'openMarketPosition',
+  CLOSE_POSITION: 'closePosition',
+  GET_POSITION: 'getPosition',
+  GET_USER_POSITIONS: 'getUserPositions',
+
+  // FundingRate
+  UPDATE_FUNDING_RATE: 'updateFundingRate',
+  GET_CURRENT_FUNDING_RATE: 'getCurrentFundingRate',
+  GET_FUNDING_INDEX: 'getFundingIndex',
+
+  // LiquidationEngine
+  LIQUIDATE_POSITION: 'liquidatePosition',
+  IS_LIQUIDATABLE: 'isLiquidatable',
+  GET_LIQUIDATION_PRICE: 'getLiquidationPrice',
+
+  // PriceOracle
+  GET_PRICE: 'getPrice',
+  UPDATE_PRICE: 'updatePrice',
+} as const;
+
+// Contract events
+export const CONTRACT_EVENTS = {
+  // MarginAccount events
+  DEPOSIT_EVENT: 'Deposited',
+  WITHDRAW_EVENT: 'Withdrawn',
+
+  // PositionManager events
+  POSITION_OPENED: 'PositionOpened',
+  POSITION_CLOSED: 'PositionClosed',
+  POSITION_UPDATED: 'PositionUpdated',
+
+  // FundingRate events
+  FUNDING_RATE_UPDATED: 'FundingRateUpdated',
+  FUNDING_PAID: 'FundingPaid',
+
+  // LiquidationEngine events
+  POSITION_LIQUIDATED: 'PositionLiquidated',
+
+  // PriceOracle events
+  PRICE_UPDATED: 'PriceUpdated',
+} as const;
+
+// Gas limits
+export const GAS_LIMITS = {
+  DEPOSIT: 100000n,
+  WITHDRAW: 150000n,
+  OPEN_POSITION: 300000n,
+  CLOSE_POSITION: 250000n,
+  LIQUIDATE: 300000n,
+  UPDATE_FUNDING: 200000n,
+} as const;

package/src/constants/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Constants used throughout the Alpha Futures SDK
+ */
+
+export * from './networks';
+export * from './contracts';
+
+// Export assets with explicit re-exports to avoid naming conflicts
+export {
+  SUBNET_MARKETS,
+  ASSET_ADDRESSES,
+  ASSET_NAMES,
+  ASSET_DECIMALS,
+  getAssetAddress,
+  getAssetSymbol,
+  isAssetSupported,
+  getAssetDecimals,
+  getSubnetMarket,
+  getAvailableSubnetMarkets,
+  isSubnetMarket,
+  getSupportedAssets,
+  getSupportedSubnetMarkets,
+  type SubnetMarketAsset,
+} from './assets';
+
+// Common constants
+export const PRECISION = 10n ** 18n; // 18 decimals precision
+export const BASIS_POINTS = 10000n; // 100% = 10000 basis points
+export const PERCENTAGE_PRECISION = 100n; // 100%
+
+// Margin constants
+export const INITIAL_MARGIN_RATIO = 3333n; // 33.33% in basis points (3x leverage)
+export const MAINTENANCE_MARGIN_RATIO = 2000n; // 20% in basis points
+export const LIQUIDATION_BONUS = 500n; // 5% in basis points
+
+// Funding rate constants
+export const FUNDING_INTERVAL = 8n * 60n * 60n; // 8 hours in seconds
+export const MAX_FUNDING_RATE = 10n; // 0.1% in basis points
+export const SKEW_SCALE = 1000000n * PRECISION; // $1M skew scale
+
+// Fee constants
+export const TRADING_FEE = 10n; // 0.1% in basis points
+export const INSURANCE_FUND_RATIO = 2000n; // 20% of fees go to insurance fund
+
+// Position constants
+export const MIN_POSITION_SIZE = 10n * PRECISION; // Minimum $10 position
+export const MAX_LEVERAGE = 3n; // Maximum 3x leverage
+
+// Oracle constants
+export const PRICE_STALENESS_THRESHOLD = 3600n; // 1 hour in seconds
+export const PRICE_DEVIATION_THRESHOLD = 2000n; // 20% max price deviation
+
+// Circuit breaker constants
+export const PRICE_MOVEMENT_THRESHOLD = 2000n; // 20% price movement triggers circuit breaker
+export const CIRCUIT_BREAKER_COOLDOWN = 3600n; // 1 hour cooldown
+
+// Error messages
+export const ERRORS = {
+  INSUFFICIENT_MARGIN: 'Insufficient margin for position',
+  POSITION_NOT_FOUND: 'Position not found',
+  INVALID_LEVERAGE: 'Invalid leverage',
+  PRICE_STALE: 'Price data is stale',
+  CIRCUIT_BREAKER_ACTIVE: 'Circuit breaker is active',
+  UNAUTHORIZED: 'Unauthorized',
+  INVALID_ASSET: 'Invalid asset',
+  POSITION_NOT_LIQUIDATABLE: 'Position is not liquidatable',
+  INSUFFICIENT_BALANCE: 'Insufficient balance',
+  BELOW_MIN_POSITION_SIZE: 'Position size below minimum',
+} as const;

package/src/constants/networks.ts

@@ -0,0 +1,182 @@
+/**
+ * Network configurations for Alpha Futures
+ */
+
+import { NetworkConfig, SubnetMarket } from '../types';
+import { SUBNET_MARKETS } from './assets';
+
+export const NETWORK_CONFIGS: Record<string, NetworkConfig> = {
+  // Bittensor Mainnet (Finney)
+  bittensor: {
+    chainId: 964,
+    name: 'Bittensor Mainnet',
+    rpcUrl: 'https://bittensor-finney.api.onfinality.io/public',
+    contracts: {
+      alpha: '0xdA50070976Da21A0E7afaB1BB0c81CD51926AE64', // Alpha Futures Proxy (Production)
+      priceOracle: '0x446A342221ed83b56fc17eA3e046dd19153beA85', // Alpha Price Oracle V5
+      collateralToken: '0x0000000000000000000000000000000000000000',
+    },
+    blockExplorer: 'https://evm.taostats.io/',
+    /** Deployed subnet markets available for trading - converted from SUBNET_MARKETS */
+    markets: Object.values(SUBNET_MARKETS).map((market) => ({
+      id: market.subnetId,
+      name: market.name,
+      marketAddress: market.marketAddress,
+      hasOraclePrice: market.hasOraclePrice,
+      symbol: market.symbol,
+      displayName: market.displayName,
+    })),
+  },
+
+  // Bittensor Testnet
+  bittensorTestnet: {
+    chainId: 965,
+    name: 'Bittensor Testnet',
+    rpcUrl: 'https://testnet.bittensor.network/rpc',
+    contracts: {
+      alpha: '0x0000000000000000000000000000000000000000',
+      priceOracle: '0x0000000000000000000000000000000000000000',
+      collateralToken: '0x0000000000000000000000000000000000000000',
+    },
+    blockExplorer: 'https://explorer.testnet.opentensor.ai',
+  },
+
+  // Ethereum Mainnet (for potential future deployment)
+  mainnet: {
+    chainId: 1,
+    name: 'Ethereum Mainnet',
+    rpcUrl: 'https://ethereum.publicnode.com',
+    contracts: {
+      alpha: '0x0000000000000000000000000000000000000000',
+      priceOracle: '0x0000000000000000000000000000000000000000',
+      collateralToken: '0x0000000000000000000000000000000000000000',
+    },
+    blockExplorer: 'https://etherscan.io',
+  },
+
+  // Sepolia Testnet
+  sepolia: {
+    chainId: 11155111,
+    name: 'Sepolia Testnet',
+    rpcUrl: 'https://ethereum-sepolia.publicnode.com',
+    contracts: {
+      alpha: '0x0000000000000000000000000000000000000000',
+      priceOracle: '0x0000000000000000000000000000000000000000',
+      collateralToken: '0x0000000000000000000000000000000000000000',
+    },
+    blockExplorer: 'https://sepolia.etherscan.io',
+  },
+
+  // Local Development - uses getters to read env vars at access time (not import time)
+  localhost: {
+    chainId: 31337,
+    name: 'Localhost',
+    rpcUrl: 'http://127.0.0.1:8545',
+    get contracts() {
+      return {
+        alpha: (process.env.ALPHA as `0x${string}`) || '0x0000000000000000000000000000000000000000',
+        priceOracle:
+          (process.env.PRICE_ORACLE as `0x${string}`) ||
+          '0x0000000000000000000000000000000000000000',
+        collateralToken:
+          (process.env.TAO_TOKEN as `0x${string}`) || '0x0000000000000000000000000000000000000000',
+      };
+    },
+  },
+
+  // Anvil Network (for deployment script)
+  anvil: {
+    chainId: 31337,
+    name: 'Anvil',
+    rpcUrl: 'http://127.0.0.1:8545',
+    contracts: {
+      alpha: '0x0000000000000000000000000000000000000000', // Will be updated by deployment script
+      priceOracle: '0x0000000000000000000000000000000000000000', // Will be updated by deployment script
+      collateralToken: '0x0000000000000000000000000000000000000000', // Will be updated by deployment script
+    },
+    blockExplorer: 'http://localhost:8545', // No block explorer for local Anvil
+  },
+
+  // Hardhat Network
+  hardhat: {
+    chainId: 31337,
+    name: 'Hardhat',
+    rpcUrl: 'http://127.0.0.1:8545',
+    contracts: {
+      alpha: '0x2279B7A0a67DB372996a5FaB50D91eAA73d2eBe6',
+      priceOracle: '0x5FC8d32690cc91D4c39d9d3abcBD16989F875707',
+      collateralToken: '0x0165878A594ca255338adfa4d48449f69242Eb8F',
+    },
+  },
+};
+
+// Default network
+export const DEFAULT_NETWORK = 'localhost';
+
+// Helper function to get network by chain ID
+export function getNetworkByChainId(chainId: number): NetworkConfig | undefined {
+  return Object.values(NETWORK_CONFIGS).find((network) => network.chainId === chainId);
+}
+
+// Helper function to validate network
+export function isValidNetwork(network: string): boolean {
+  return network in NETWORK_CONFIGS;
+}
+
+// Helper function to get current network config
+export function getCurrentNetwork(network?: string): NetworkConfig {
+  const selectedNetwork = network || DEFAULT_NETWORK;
+  if (!isValidNetwork(selectedNetwork)) {
+    throw new Error(`Invalid network: ${selectedNetwork}`);
+  }
+  return NETWORK_CONFIGS[selectedNetwork];
+}
+
+// Helper function to get all supported networks
+export function getSupportedNetworks(): string[] {
+  return Object.keys(NETWORK_CONFIGS);
+}
+
+// Helper function to get network name by chain ID
+export function getNetworkName(chainId: number): string | undefined {
+  const network = getNetworkByChainId(chainId);
+  return network?.name;
+}
+
+/**
+ * Get subnet markets for a specific network
+ */
+export function getNetworkSubnetMarkets(network: string): SubnetMarket[] {
+  const networkConfig = NETWORK_CONFIGS[network];
+  return networkConfig?.markets || [];
+}
+
+/**
+ * Get subnet market by symbol from a specific network
+ */
+export function getSubnetMarketBySymbol(network: string, symbol: string): SubnetMarket | undefined {
+  const markets = getNetworkSubnetMarkets(network);
+  return markets.find((market) => market.symbol.toLowerCase() === symbol.toLowerCase());
+}
+
+/**
+ * Get subnet market by ID from a specific network
+ */
+export function getSubnetMarketById(network: string, subnetId: number): SubnetMarket | undefined {
+  const markets = getNetworkSubnetMarkets(network);
+  return markets.find((market) => market.id === subnetId);
+}
+
+/**
+ * Check if a network supports subnet markets
+ */
+export function networkHasSubnetMarkets(network: string): boolean {
+  return getNetworkSubnetMarkets(network).length > 0;
+}
+
+/**
+ * Get all networks that support subnet markets
+ */
+export function getSubnetMarketNetworks(): string[] {
+  return Object.keys(NETWORK_CONFIGS).filter((network) => networkHasSubnetMarkets(network));
+}

package/src/contracts/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Viem-based contract wrappers for Alpha Futures
+ */
+
+export * from './viem';