@megatao/sdk 1.1.0

package/src/types/alpha.ts

@@ -0,0 +1,358 @@
+/**
+ * Type definitions for AlphaFuturesMonolith contract
+ */
+
+import { Address } from 'viem';
+
+// ============ Position and Order Types ============
+
+export interface MonolithPosition {
+  notionalValue: bigint; // Position value in collateral terms
+  margin: bigint;
+  entryPrice: bigint;
+  isLong: boolean;
+  lastUpdated: bigint;
+  fundingIndex: bigint;
+  leverage: bigint;
+  liquidationPrice: bigint;
+}
+
+export interface MonolithOrder {
+  trader: Address;
+  notionalValue: bigint; // Order notional value in collateral terms
+  price: bigint;
+  isBuy: boolean;
+  margin: bigint;
+  timestamp: bigint;
+  leverage: bigint;
+}
+
+export interface MonolithMarket {
+  isActive: boolean;
+  maxLeverage: bigint;
+  maintenanceMargin: bigint;
+  liquidationFee: bigint;
+  lastFundingUpdate: bigint;
+  fundingIndex: bigint;
+  fundingRate: bigint;
+  longOpenInterest: bigint;
+  shortOpenInterest: bigint;
+}
+
+export interface OrderBook {
+  bestBid: `0x${string}`; // bytes16
+  bestAsk: `0x${string}`; // bytes16
+}
+
+export interface DepthLevel {
+  price: bigint;
+  notionalValue: bigint; // Liquidity notional value at this price level
+  orderCount: bigint;
+}
+
+export interface VWAPResult {
+  vwap: bigint;
+  slippage: bigint;
+  totalNotional: bigint; // Changed from totalSize to match Solidity struct (IAlphaStorage.sol:222)
+  priceImpact: bigint;
+}
+
+export interface SpreadInfo {
+  bidPrice: bigint;
+  askPrice: bigint;
+  spread: bigint;
+  spreadPercent: bigint;
+}
+
+export interface OrderDetails {
+  trader: Address;
+  isLong: boolean;
+  notionalValue: bigint;
+  price: bigint;
+  reduceOnly: boolean;
+  next: Bytes16;
+  prev: Bytes16;
+}
+
+/**
+ * Position details returned by getPositionDetails
+ * Matches contract struct IAlphaStorage.PositionDetails
+ */
+export interface PositionDetails {
+  owner: Address;
+  market: Address;
+  isLong: boolean;
+  notionalValue: bigint;
+  margin: bigint;
+  entryPrice: bigint;
+  markPrice: bigint;
+  pricePnl: bigint; // Price movement P&L only (entry vs mark price)
+  fundingPayment: bigint;
+  interestPayment: bigint; // Interest fee owed (always negative)
+  marginRatio: bigint;
+  liquidationPrice: bigint;
+  liquidatable: boolean;
+}
+
+// ============ Parameter Types ============
+
+/**
+ * Parameters for opening a market position
+ * UPDATED: Changed from asset-quantity model to collateral-based model
+ * - Previously: Specified token quantity (size) to trade
+ * - Now: Specify collateral amount (margin) to risk with leverage
+ */
+export interface MarketPositionParams {
+  market: Address;
+  isLong: boolean;
+  margin: bigint; // Collateral amount to risk
+  leverage: bigint; // 1e18 format (e.g., 3e18 for 3x)
+  maxSlippage: bigint;
+}
+
+export interface LimitOrderParams {
+  market: Address;
+  isBuy: boolean;
+  margin: bigint; // Collateral amount to risk
+  leverage: bigint; // 1e18 format (e.g., 3e18 for 3x)
+  price: bigint;
+  // reduceOnlyType: Uses OrderType enum values
+  // 0 = Normal: Regular limit order, placed on natural side (BUY→BID, SELL→ASK)
+  // 1 = TakeProfit: Reduce-only, natural side, triggers on favorable price
+  // 2 = StopLoss: Reduce-only, OPPOSITE side, triggers on adverse price (dual-trigger)
+  reduceOnlyType: number;
+}
+
+// ============ State Types ============
+
+export interface VaultState {
+  totalReserves: bigint;
+  availableReserves: bigint;
+  totalExposure: bigint;
+  unrealizedPnl: bigint;
+}
+
+export interface FundingState {
+  fundingRate: bigint;
+  fundingIndex: bigint;
+  lastUpdateTime: bigint;
+  nextFundingTime: bigint;
+}
+
+// ============ Execution Types ============
+
+export interface ExecutionPlan {
+  orderbookSize: bigint;
+  vaultSize: bigint;
+  totalSize: bigint;
+  expectedSlippage: bigint;
+  effectivePrice: bigint;
+  feasible: boolean;
+}
+
+export interface ExecutionStrategyAnalysis {
+  orderbookLiquidity: bigint;
+  vaultCapacity: bigint;
+  orderbookSlippage: bigint;
+  vaultSlippage: bigint;
+  hybridSlippage: bigint;
+  recommendedSplit: bigint;
+  recommendedStrategy: number;
+}
+
+export interface MarketLiquidityAnalysis {
+  totalBidLiquidity: bigint;
+  totalAskLiquidity: bigint;
+  bidDepth: bigint;
+  askDepth: bigint;
+  spreadPercent: bigint;
+  marketScore: bigint;
+}
+
+export interface SlippageBreakdown {
+  baseSlippage: bigint;
+  sizeImpact: bigint;
+  marketDepthFactor: bigint;
+  exposureEffect: bigint;
+  volatilityAdjustment: bigint;
+  totalSlippage: bigint;
+}
+
+// ============ Event Types ============
+
+export interface MarginDepositedEvent {
+  trader: Address;
+  amount: bigint;
+}
+
+export interface PositionOpenedEvent {
+  positionId: `0x${string}`; // bytes16
+  trader: Address;
+  market: Address;
+  isLong: boolean;
+  notionalValue: bigint;
+  margin: bigint;
+}
+
+export interface PositionClosedEvent {
+  positionId: `0x${string}`; // bytes16
+  trader: Address;
+  pnl: bigint;
+}
+
+export interface OrderPlacedEvent {
+  orderId: `0x${string}`; // bytes16
+  trader: Address;
+  market: Address;
+  isBuy: boolean;
+  notionalValue: bigint;
+  price: bigint;
+}
+
+export interface HybridOrderExecutedEvent {
+  trader: Address;
+  market: Address;
+  orderbookFilled: bigint;
+  vaultFilled: bigint;
+  avgPrice: bigint;
+}
+
+// ============ Helper Types ============
+
+export type Bytes16 = `0x${string}`;
+export type Bytes32 = `0x${string}`;
+
+export interface MonolithConfig {
+  precision: bigint;
+  basisPoints: bigint;
+  maxLeverage: bigint;
+  defaultLeverage: bigint;
+  minPositionSize: bigint;
+  liquidationThreshold: bigint;
+  partialLiquidationThreshold: bigint;
+  liquidationFee: bigint;
+  fundingInterval: bigint;
+  maxFundingRate: bigint;
+  maxExposurePerAsset: bigint;
+  maxTotalUtilization: bigint;
+  criticalUtilizationBps: bigint;
+  maxLossRateBps: bigint;
+  maxLiquidationsPerBlock: bigint;
+}
+
+// ============ View Function Response Types ============
+
+export interface MarketInfo {
+  isActive: boolean;
+  maxLeverage: bigint;
+  maintenanceMargin: bigint;
+  liquidationFee: bigint;
+  longOpenInterest: bigint;
+  shortOpenInterest: bigint;
+  fundingRate: bigint;
+  lastFundingUpdate: bigint;
+}
+
+export interface MarginInfo {
+  balance: bigint;
+  locked: bigint;
+  available: bigint;
+}
+
+export interface AccountSummary {
+  depositedBalance: bigint;
+  accountEquity: bigint;
+  unrealizedPnl: bigint;
+  lockedMargin: bigint;
+  availableMargin: bigint;
+}
+
+export interface PositionSummary {
+  totalPositions: bigint;
+  totalMargin: bigint;
+  totalUnrealizedPnl: bigint;
+  totalSize: bigint;
+}
+
+export interface VaultStats {
+  totalReserves: bigint;
+  availableReserves: bigint;
+  totalExposure: bigint;
+  unrealizedPnl: bigint;
+}
+
+export interface VaultExposure {
+  longExposure: bigint;
+  shortExposure: bigint;
+  netExposure: bigint;
+  utilizationRate: bigint;
+}
+
+export interface LiquidationStatus {
+  isLiquidatable: boolean;
+  marginRatio: bigint;
+  requiredMargin: bigint;
+  liquidationPrice: bigint;
+}
+
+export interface MarketStatistics {
+  totalOrders: bigint;
+  bidOrders: bigint;
+  askOrders: bigint;
+  averageOrderSize: bigint;
+  medianBidPrice: bigint;
+  medianAskPrice: bigint;
+}
+
+export interface ExecutionMetrics {
+  orderbookFilled: bigint;
+  vaultFilled: bigint;
+  avgPrice: bigint;
+  slippage: bigint;
+}
+
+export interface MarketLiquidationStats {
+  totalLiquidations: bigint;
+  totalLiquidationValue: bigint;
+  liquidationsLast24h: bigint;
+}
+
+export interface BadDebtInfo {
+  totalCovered: bigint;
+  eventCount: bigint;
+}
+
+export interface VaultFundingStats {
+  collected: bigint;
+  paid: bigint;
+  net: bigint;
+}
+
+export interface VaultFundingInfo {
+  fundingBalance: bigint;
+  vaultIndex: bigint;
+}
+
+export interface LiquidationCascadeRisk {
+  shouldTrigger: boolean;
+  severity: number;
+}
+
+export interface TopKeeperInfo {
+  keepers: Address[];
+  liquidationCounts: bigint[];
+  rewards: bigint[];
+}
+
+export interface CumulativeDepthResult {
+  prices: bigint[];
+  cumulativeSizes: bigint[];
+  totalDepth: bigint;
+}
+
+export interface MarketImpactEstimate {
+  averagePrice: bigint;
+  worstPrice: bigint;
+  priceImpact: bigint;
+  filledFromOrderbook: bigint;
+}

package/src/types/client.ts

@@ -0,0 +1,27 @@
+/**
+ * Client-related type definitions
+ */
+
+import { PublicClient, WalletClient, Chain } from 'viem';
+
+export interface AlphaFuturesConfig {
+  publicClient?: PublicClient;
+  walletClient?: WalletClient;
+  rpcUrl?: string;
+  privateKey?: string;
+  network?: 'mainnet' | 'testnet' | 'localhost';
+  customContracts?: ContractAddresses;
+  chain?: Chain;
+}
+
+export interface ContractAddresses {
+  alpha: string;
+  priceOracle: string;
+  collateralToken: string;
+}
+
+export enum Network {
+  MAINNET = 'mainnet',
+  TESTNET = 'testnet',
+  LOCALHOST = 'localhost',
+}

package/src/types/contracts.ts

@@ -0,0 +1,74 @@
+/**
+ * Contract interface type definitions
+ */
+
+import { Hash, Address } from 'viem';
+import { TransactionOptions } from './index';
+
+// Base contract interface
+export interface BaseContract {
+  address: Address;
+  // Viem uses different connection patterns, removing connect method
+}
+
+// MarginAccount contract interface
+export interface IMarginAccount extends BaseContract {
+  deposit(amount: bigint, options?: TransactionOptions): Promise<Hash>;
+  withdraw(amount: bigint, options?: TransactionOptions): Promise<Hash>;
+  getBalance(user: Address): Promise<bigint>;
+  getAvailableBalance(user: Address): Promise<bigint>;
+  getLockedMargin(user: Address): Promise<bigint>;
+}
+
+// PositionManager contract interface
+export interface IPositionManager extends BaseContract {
+  openMarketPosition(
+    asset: Address,
+    isLong: boolean,
+    margin: bigint, // Collateral to risk, not asset size
+    leverage: bigint, // 1e18 format (e.g., 3e18 for 3x)
+    maxSlippage: bigint, // Max slippage in basis points (e.g., 100 = 1%)
+    options?: TransactionOptions,
+  ): Promise<Hash>;
+
+  closePosition(
+    positionId: bigint,
+    notionalValue: bigint,
+    options?: TransactionOptions,
+  ): Promise<Hash>; // Notional value to close
+
+  getPosition(positionId: bigint): Promise<any>;
+  getUserPositions(user: Address): Promise<bigint[]>;
+  getActivePositions(asset: Address): Promise<bigint[]>;
+}
+
+// FundingRate contract interface
+export interface IFundingRate extends BaseContract {
+  updateFundingRate(asset: Address, options?: TransactionOptions): Promise<Hash>;
+  getCurrentFundingRate(asset: Address): Promise<bigint>;
+  getFundingIndex(asset: Address): Promise<bigint>;
+  getNextFundingTime(asset: Address): Promise<bigint>;
+}
+
+// LiquidationEngine contract interface
+export interface ILiquidationEngine extends BaseContract {
+  liquidatePosition(positionId: bigint, options?: TransactionOptions): Promise<Hash>;
+
+  isLiquidatable(positionId: bigint): Promise<boolean>;
+  getLiquidationPrice(positionId: bigint): Promise<bigint>;
+}
+
+// ProtocolVault contract interface
+export interface IProtocolVault extends BaseContract {
+  getTotalReserves(): Promise<bigint>;
+  getInsuranceFund(): Promise<bigint>;
+  getUnmatchedLongs(asset: Address): Promise<bigint>;
+  getUnmatchedShorts(asset: Address): Promise<bigint>;
+}
+
+// PriceOracle contract interface
+export interface IPriceOracle extends BaseContract {
+  getPrice(asset: Address): Promise<bigint>;
+  updatePrice(asset: Address, price: bigint, options?: TransactionOptions): Promise<Hash>;
+  getLatestPriceData(asset: Address): Promise<[bigint, bigint]>; // [price, timestamp]
+}

package/src/types/funding.ts

@@ -0,0 +1,31 @@
+/**
+ * Funding rate related type definitions
+ */
+
+import { Address } from 'viem';
+
+export interface FundingRate {
+  rate: bigint;
+  timestamp: bigint;
+  longOpenInterest: bigint;
+  shortOpenInterest: bigint;
+}
+
+export interface FundingPayment {
+  positionId: bigint;
+  payment: bigint;
+  timestamp: bigint;
+}
+
+export interface FundingRateConfig {
+  baseRate: bigint;
+  maxRate: bigint;
+  fundingInterval: bigint;
+  skewScale: bigint;
+}
+
+export interface FundingIndex {
+  asset: Address;
+  index: bigint;
+  timestamp: bigint;
+}

package/src/types/index.ts

@@ -0,0 +1,108 @@
+/**
+ * Type definitions for Alpha Futures SDK
+ */
+
+import { Address } from 'viem';
+
+// Re-export all types
+export * from './client';
+export * from './contracts';
+export * from './positions';
+export * from './margin';
+export * from './funding';
+export * from './liquidation';
+export * from './oracle';
+
+// Common types used across the SDK
+export interface TransactionOptions {
+  gas?: bigint;
+  gasPrice?: bigint;
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+  nonce?: number;
+  value?: bigint;
+  waitForConfirmation?: boolean; // Custom SDK option, not passed to viem
+}
+
+export interface CallOptions {
+  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
+  blockNumber?: bigint;
+}
+
+export interface EventFilter {
+  fromBlock?: bigint | 'latest' | 'earliest' | 'pending';
+  toBlock?: bigint | 'latest' | 'earliest' | 'pending';
+  address?: Address | Address[];
+  topics?: string[];
+}
+
+/**
+ * Subnet market configuration for Alpha Futures protocol
+ */
+export interface SubnetMarket {
+  /** Subnet ID on the Bittensor network */
+  id: number;
+  /** Human-readable name of the subnet */
+  name: string;
+  /** Market contract address for this subnet */
+  marketAddress: `0x${string}`;
+  /** Whether oracle pricing is available */
+  hasOraclePrice: boolean;
+  /** Symbol used for trading */
+  symbol: string;
+  /** Full name for display */
+  displayName: string;
+}
+
+export interface NetworkConfig {
+  chainId: number;
+  name: string;
+  rpcUrl?: string;
+  contracts: {
+    alpha: Address;
+    priceOracle: Address;
+    collateralToken: Address;
+  };
+  markets?: SubnetMarket[];
+  collateralTokenInfo?: {
+    symbol: string;
+    decimals: number;
+    name: string;
+  };
+  blockExplorer?: string;
+}
+
+export interface ClientConfig {
+  rpcUrl?: string;
+  privateKey?: string;
+  network?: string;
+  networkConfig?: NetworkConfig;
+}
+
+// Subnet market constants for trading (replaces legacy Alpha Token constants)
+export const SubnetMarkets = {
+  BITMIND: '0x0000000000000000000000000000000000000022' as Address,
+  CHUTES: '0x0000000000000000000000000000000000000040' as Address,
+  AFFINE: '0x0000000000000000000000000000000000000078' as Address,
+  RIDGES: '0x0000000000000000000000000000000000000003E' as Address,
+} as const;
+
+// Legacy Alpha Token constants for backward compatibility
+export const AlphaToken = {
+  ALPHA_BTC: '0x0000000000000000000000000000000000000001' as Address,
+  ALPHA_ETH: '0x0000000000000000000000000000000000000003' as Address,
+  ALPHA_SOL: '0x0000000000000000000000000000000000000004' as Address,
+  // New subnet markets
+  BITMIND: SubnetMarkets.BITMIND,
+  CHUTES: SubnetMarkets.CHUTES,
+  AFFINE: SubnetMarkets.AFFINE,
+  RIDGES: SubnetMarkets.RIDGES,
+} as const;
+
+// Additional type for backward compatibility
+export interface AlphaTokenInfo {
+  symbol: string;
+  address: Address;
+  decimals: number;
+  name: string;
+}

package/src/types/liquidation.ts

@@ -0,0 +1,23 @@
+/**
+ * Liquidation-related type definitions
+ */
+
+import { Address } from 'viem';
+
+export interface LiquidationParams {
+  positionId: bigint;
+}
+
+export interface LiquidationResult {
+  positionId: bigint;
+  liquidator: Address;
+  remainingMargin: bigint;
+  liquidationBonus: bigint;
+  timestamp: bigint;
+}
+
+export interface LiquidationConfig {
+  maintenanceMarginRatio: bigint;
+  liquidationBonus: bigint;
+  insuranceFundRatio: bigint;
+}

package/src/types/margin.ts

@@ -0,0 +1,34 @@
+/**
+ * Margin-related type definitions
+ */
+
+import { Address } from 'viem';
+
+export interface MarginAccount {
+  balance: bigint;
+  lockedMargin: bigint;
+  availableBalance: bigint;
+  totalPositions: number;
+}
+
+export interface MarginRequirement {
+  initialMargin: bigint;
+  maintenanceMargin: bigint;
+  currentMargin: bigint;
+  marginRatio: bigint;
+}
+
+export interface DepositParams {
+  amount: bigint;
+}
+
+export interface WithdrawParams {
+  amount: bigint;
+}
+
+export interface MarginUpdateEvent {
+  user: Address;
+  amount: bigint;
+  isDeposit: boolean;
+  timestamp: bigint;
+}

package/src/types/oracle.ts

@@ -0,0 +1,24 @@
+/**
+ * Oracle-related type definitions
+ */
+
+import { Address } from 'viem';
+
+export interface PriceData {
+  asset: Address;
+  price: bigint;
+  timestamp: bigint;
+  confidence?: bigint;
+}
+
+export interface OracleConfig {
+  heartbeat: bigint;
+  deviation: bigint;
+  decimals: number;
+}
+
+export interface PriceFeed {
+  asset: Address;
+  oracle: Address;
+  isActive: boolean;
+}